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


106

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?

Réponses:


127

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.


8
Merci pour l'indice «M»!
Jedidja

2
L'aperçu en direct de Github Markdown ne rend pas les tableaux ...
Rubens Mariuzzo

2
Si vous préférez un screencast vidéo, j'en ai créé un expliquant Markdown ici: mikemclin.net/markdown-syntax-language
Mike McLin

2
@Mike McLin Grande vidéo expliquant la syntaxe et les concepts derrière! Excellente intro pour le débutant de Markdown comme moi :)
Brock

1
L'aperçu en direct de démarque ne semble pas non plus obéir aux règles de github concernant les traits de soulignement au milieu des mots, par exemple my_setup_script.py ne mettra pas en italique «setup» dans github mais le fera dans l'aperçu. C'est utile, mais juste pour que les gens sachent.
user2428107

11

( 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 .


5

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.

entrez la description de l'image ici

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.

entrez la description de l'image ici

  • 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 .


4

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 .

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

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

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


1

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.


1

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

entrez la description de l'image ici


0

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.

En utilisant notre site, vous reconnaissez avoir lu et compris notre politique liée aux cookies et notre politique de confidentialité.
Licensed under cc by-sa 3.0 with attribution required.