Qu'est-ce qu'un fichier README au format Markdown sur Github?

27

Je ne sais pas exactement quel est le format, s'il y a des exigences systématiques / en ligne de commande pour le créer, etc.

Fondamentalement, juste pour avoir besoin de connaître les spécifications et s'il existe des étapes techniques pour générer le fichier README.

github bévues
la source
4
Non, juste un fichier texte que vous éditez à la main. Quant à la syntaxe, en.wikipedia.org/wiki/Markdown
Andrea
3
c'est le même format wiki-edit que ce côté utilise.
k3b
+1 @Andrea: Merci, bien que je puisse penser à plus d'une poignée de formats de démarques, quel format et quelle version sont attendus sur Github? De plus, votre commentaire se lit comme plus d'une réponse, veuillez l'afficher comme réponse complète. Merci encore!
bévue
+1 @ K3b: Croyez que vous êtes sur quelque chose, parlez-vous de l'utilisation de Gollum par Github , qui permet par exemple un lien relatif? Si oui, veuillez poster ceci comme réponse, car je pense que c'est la bonne réponse. Merci!
bévue

Réponses:

37

Markdown est une syntaxe simple pour fournir des informations sémantiques et représenter une mise en forme courante en texte brut. Daring Fireball a un guide de syntaxe génial pour le démarquage standard . GitHub utilise ensuite une variante de ce qu'ils appellent GitHub Flavored Markdown .

Pour configurer votre fichier lisez-moi, créez simplement un fichier texte et nommez-le README (ou README.md / README.markdown) et validez-le à la racine de votre référentiel. GitHub le récupérera alors en tant que fichier Lisez-moi du projet.

Kim Burgess
la source
2
J'ai également créé une vidéo expliquant comment utiliser Markdown. Vous pouvez le trouver ici: mikemclin.net/markdown-syntax-language
Mike McLin
9

Wikipedia - Markdown fait référence à la page "GitHub Flavoured Markdown - Introduction" ( archv. )

Citation de la page:

GitHub utilise ce que nous appelons «GitHub Flavored Markdown» (GFM) pour les messages, les problèmes et les commentaires. Il diffère de Markdown (SM) standard de plusieurs façons importantes et ajoute des fonctionnalités supplémentaires.

La page donne également une description des différences avec Markdown standard.

Il y a aussi plus d'informations sur la façon dont Markdown est réellement rendu par GitHub:

Si vous êtes intéressé par la façon dont nous rendons les fichiers Markdown, vous voudrez peut-être consulter Redcarpet , notre interface Ruby à la bibliothèque Sundown .

(Apparemment, Sundown est le véritable analyseur Markdown utilisé derrière les rideaux.)

Pour ajouter une couche d'abstraction supplémentaire, Sundown est un fork d'un autre analyseur Markdown :-)
Citation de la page GitHub de Sundown :

Sundown est un analyseur Markdown basé sur le code original de la bibliothèque Upskirt de Natacha Porté.

Christian Specht
la source
1

C'est très étrange, mais il semble que GitHub n'utilise pas le GitHub-Flavored Markdown (GFM) lors du rendu d'un fichier README.

GitHub utilise «GitHub Flavored Markdown» ou GFM, sur l'ensemble du site - dans les problèmes, les commentaires et les demandes de tirage.

Au lieu de cela, il semble utiliser une version appelée redcarpet dans le cadre du projet de balisage GitHub . Ils prennent également en charge plusieurs autres formats de balisage, notamment MediaWiki. Utilisez simplement la bonne extension de fichier et GitHub rendra le balisage.

Si vous voulez voir les différences entre les deux versions différentes de Markdown, lisez la description de GFM et ses fonctionnalités supplémentaires .

Don Kirkby
la source
1
redcarpet et Github Flavored Markdown sont deux concepts distincts mais complémentaires, et non des implémentations concurrentes de la même chose. redcarpet est essentiellement un compilateur qui prend les choses écrites dans le langage Github Flavored Markdown et génère du HTML ou du XHTML.
8bittree