Travailler avec README.md sur github.com

Je ne connais pas très bien 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?

Y a-t-il un outil que je peux “examiner mes documents localement dans mon navigateur” avant de lancer le fichier README mis à jour sur mon repository github?

Le balisage en question est appelé par coïncidence Markdown , créé par John Gruber, auteur du blog Daring Fireball . La source originale de Markdown peut être trouvée à Daring Fireball – Markdown .

Il existe de nombreux dialectes de Markdown, la documentation de Github se trouve sur la page Github Flavored Markdown .

bon conseil de cette page:

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

Vous pouvez également utiliser la page Github Markdown Live Preview pour tester vos documents Markdown.

Mise à jour 2012-11-08 : Des efforts sont en cours pour normaliser la syntaxe Markdown. Voir L’avenir de Markdown – Jeff Atwood, Coding Horror et W3C Markdown Community Group .

Mise à jour 2014-09-09 : CommonMark une norme de démarque et des spécifications ont été publiées.

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

Un peu tard au jeu, mais j’ai écrit une petite CLI en Python. Il s’appelle Grip (Prévisualisation instantanée de Github Readme) . En plus de la réponse de Pasortingck, cela vous permettra de “revoir mes documents localement dans mon navigateur”.

Installez-le avec:

$ pip install grip 

Et pour l’utiliser, simplement:

 $ grip 

Ensuite, visitez localhost:5000 pour afficher le fichier readme.md à cet emplacement.

Vous pouvez également spécifier votre propre fichier:

 $ grip CHANGES.md 

Et changez le port:

 $ grip 8080 

Ou combinez les deux précédentes:

 $ grip CHANGES.md 8080 

Vous pouvez même rendre le Markdown GitHub-Flavored (c’est-à-dire comment les commentaires et les problèmes sont rendus), éventuellement avec le contexte repo pour les références aux liens hypertextes automatiques à d’autres problèmes:

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

Pour plus de concision, consultez le rest des options et leurs détails à l’aide de l’aide de la CLI:

 $ grip -h 

Caractéristiques notables:

  • Rend les pages à apparaître 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. Check it out .

Notez que depuis février 2014, avec ” Différé Prose Diffs “, vous pouvez également voir la version rendue d’un diff sur un fichier de démarques:

Les validations et les requêtes d’extraction, y compris les fichiers en prose, comportent désormais des vues source et rendues .

https://f.cloud.github.com/assets/17715/1999080/7f0c15a2-853e-11e3-95dc-1d7737e1ec20.png

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

https://f.cloud.github.com/assets/17715/2005588/714cb5ea-86ef-11e3-9e92-a0d11ba6084f.png

Il y a un bon éditeur en ligne / live ici:

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

Il y a aussi un bouton Preview sur GitHub.

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

entrer la description de l'image ici

À mon humble avis, l’ éditeur en direct est meilleur que celui actuellement disponible sur GitHub.

METTRE À JOUR

Tout à l’heure, après avoir recherché Markdown et Visual Studio, j’ai constaté que si vous utilisez VS, vous pouvez installer Web Essentials et bénéficier de la prise en charge de Markdown directement dans Visual Studio. C’est super!

Il a:

  • Mise en évidence de la syntaxe => Colorisation complète pour la syntaxe Markdown
  • Intellisense pour les langages intégrés ( W00T ) => La fonctionnalité de langage intégré de GitHub est entièrement compatible avec la prise en charge de la syntaxe du langage “ `.

entrer la description de l'image ici

  • Fenêtre d’aperçu => Voir une fenêtre d’aperçu côte à côte du code HTML rendu
  • Comstackr en HTML => Cliquez avec le bouton droit de la souris sur un fichier Markdown et sélectionnez Comstackr Markdown to HTML. Cela générera un fichier .html nested sous le fichier Markdown et restra synchronisé à mesure que le fichier Markdown sera modifié.
  • Feuille de style personnalisée => Vous pouvez append 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 .

Une autre option – le nouvel éditeur de texte de Github, Atom, affichera les balises au format github lorsque vous les éditez. Voir https://atom.io/

Je ne suis pas sûr que ce soit gratuit (comme dans la bière) à long terme.

A ce jour, vous pouvez prévisualiser, au fur et à mesure que vous éditez le fichier.

entrer la description de l'image ici

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

  1. Possibilité de modifier hors ligne
  2. Pas seulement des démarques régulières, mais la réelle réduction de saveur de Github

C’est ce que j’ai finalement décidé sur: 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. 

Donc j’ai aliasé:

 alias gm='gfms -a -p 8070' 

L’utilisation de l’option -p frappe l’API Github et utilise le CSS actuel de Github, il n’y a donc pas de surprise.