Utilisation de README.md sur github.com [fermé]

Je ne suis pas trop familier avec le langage de balisage léger utilisé par github lors de la mise à jour des fichiers README.

Où sont les ressources que je peux lire sur la façon d'écrire la syntaxe de balisage appropriée pour les fichiers README / wiki de ma bibliothèque open source?

Et y a-t-il un outil que je peux "revoir mes documents localement dans mon navigateur" avant de pousser le README mis à jour dans mon référentiel github?

Le balisage en question s'appelle par hasard Markdown , créé par John Gruber, auteur du blog Daring Fireball . La source originale de Markdown se trouve sur Daring Fireball - Markdown .

Il existe de nombreux dialectes Markdown, la documentation de Github est disponible sur la page Github Flavored Markdown .

belle astuce de cette page:

appuyez sur M sur n'importe quelle page Github avec un éditeur Markdown pour révéler la feuille de triche.

Vous pouvez également utiliser la page Aperçu en direct de Github Markdown pour tester vos documents Markdown.

Mise à jour 08/11/2012 : Des efforts sont en cours pour normaliser la syntaxe Markdown. Voir The Future of Markdown - Jeff Atwood, Coding Horror et W3C Markdown Community Group .

Mise à jour 09/09/2014 : CommonMark, une norme et une spécification de démarque ont été publiées.

( Re-publier cette réponse avec quelques modifications.)

Un peu tard dans le jeu, mais j'ai écrit une petite CLI en Python. Il s'appelle Grip (Github Readme Instant Preview) . En plus de la réponse de Patrick, cela vous permettra de «consulter mes documents localement dans mon navigateur».

Installez-le avec:

$ pip install grip

Et pour l'utiliser, simplement:

$ grip

Ensuite, visitez localhost:5000pour afficher le readme.mdfichier à cet endroit.

Vous pouvez également spécifier votre propre fichier:

$ grip CHANGES.md

Et changez le port:

$ grip 8080

Ou combinez les deux précédents:

$ grip CHANGES.md 8080

Vous pouvez même rendre GitHub-Flavored Markdown (c'est-à-dire comment les commentaires et les problèmes sont rendus), éventuellement avec un contexte de dépôt pour créer des liens hypertextes automatiques vers d'autres problèmes:

$ grip --gfm --context=username/repo issue.md

Par souci de concision, consultez le reste des options et leurs détails à l'aide de l'aide CLI:

$ grip -h

Caractéristiques notables:

• Rend les pages pour qu'elles apparaissent exactement comme sur GitHub
• Blocs clôturés
• API Python
• Naviguer entre les fichiers liés
• Exporter un document rendu dans un fichier

J'espère que cela t'aides. Vérifiez-le .

Il y a un bel éditeur en ligne / en direct ici:

http://jbt.github.io/markdown-editor/

Il y a aussi un Previewbouton sur GitHub.

Voyez dans la capture d'écran suivante que ce bouton apparaît lorsque j'ai cliqué sur Modifier README.md.

IMHO l' éditeur en direct est meilleur que l'actuel disponible sur GitHub.

METTRE À JOUR

Tout à l'heure, j'ai trouvé après avoir recherché Markdownet Visual Studio que si vous utilisez VS, vous pouvez installer Web Essentials et bénéficier d'une Markdownprise en charge directement à partir de Visual Studio. C'est super!

Il a:

• Mise en évidence de la syntaxe => Colorisation complète pour la syntaxe Markdown
• Intellisense pour les langues intégrées ( W00T ) => La fonctionnalité de langage intégré de GitHub est entièrement prise en charge par la prise en charge de la syntaxe du langage.

• Fenêtre d'aperçu => Voir une fenêtre d'aperçu côte à côte du HTML rendu
• Compiler en HTML => Cliquez avec le bouton droit sur n'importe quel fichier Markdown et sélectionnez Compile Markdown en HTML. Cela générera un fichier .html imbriqué sous le fichier Markdown et il restera synchronisé à mesure que le fichier Markdown change.
• Feuille de style personnalisée => Vous pouvez ajouter une feuille de style spécifique à la solution pour contrôler les styles de la fenêtre d'aperçu.

Détails à ce sujet ici .

Notez que depuis février 2014, avec " Rendered Prose Diffs ", vous pouvez également voir la version rendue d'un diff sur un fichier markdown:

Les validations et les demandes d'extraction, y compris les fichiers de prose, comportent désormais des vues source et rendues .

Les modifications non textuelles apparaissent avec un soulignement en pointillé discret. Survolez le texte pour voir ce qui a changé:

Une autre option - Le nouvel éditeur de texte de Github, Atom, rendra le markdown à la saveur de Github lorsque vous le modifiez. Voir https://atom.io/

Je ne sais pas si ce sera gratuit (comme dans la bière) à long terme.

À partir d'aujourd'hui, vous pouvez prévisualiser au fur et à mesure que vous modifiez le fichier.

Je n'ai pas trouvé que les autres outils étaient assez bons - je voulais:

1. Possibilité de modifier hors ligne
2. Pas seulement une démarque régulière, mais la démarque aromatisée à Github

C'est ce sur quoi j'ai finalement décidé: https://github.com/ypocat/gfms

> gfms

Github Flavored Markdown Server.
Run in your project's root directory.
Usage: gfms

Options:
  -p, --port              Port number to listen at.        [required]
  -h, --host              Host address to bind to.         [default: "localhost"]
  --proxy                 if behind a proxy, proxy url.
  -a, --api               Render using Github API.
  -n, --no-api-on-reload  Disable usage of Github API when the doc is manually reloaded.

Alors j'ai aliasé:

alias gm='gfms -a -p 8070'

L'utilisation de l' -poption atteint l'API Github et utilise le CSS Github actuel, donc il n'y a pas de surprises.