web-dev-qa-db-fra.com

Travailler avec README.md sur github.com

Je ne connais pas trop 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 existe-t-il un outil que je puisse "examiner mes documents localement dans mon navigateur" avant de transférer le fichier mis à jour README dans mon référentiel github?

githubmarkdownmarkup
106
Calvin Cheng

Le balisage en question est appelé par hasard Markdown , créé par John Gruber, auteur du blog Daring Fireball . La source originale de Markdown se trouve à l’adresse Daring Fireball - Markdown .

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

Belle astuce de cette page:

appuyez sur [~ # ~] m [~ # ~] sur une page Github dotée d'un éditeur Markdown pour afficher la feuille de triche.

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 standardiser la syntaxe de Markdown. Voir L'avenir de Markdown - Jeff Atwood, Coder l'horreur et Groupe de la communauté du Markdown W3C .

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

127
Patrick Klingemann

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

Un peu tard dans le jeu, mais j’ai écrit un petit CLI en Python. Cela s'appelle Grip (Github Readme Instant Preview) . En ajoutant à 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

Puis visitez localhost:5000 pour afficher le readme.md fichier à 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 générer un rendu GitHub-Flavored Markdown (c’est-à-dire comment les commentaires et les problèmes sont restitués), éventuellement avec le contexte du référentiel pour créer des hyperliens vers des références à d’autres problèmes:

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

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

$ grip -h

Caractéristiques notables:

  • Rend les pages 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 .

10
Joe

Il y a un joli é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 sur README.md.

enter image description here

IMHO le live éditeur est meilleur que celui actuellement disponible sur GitHub.

[~ # ~] met à jour [~ # ~]

Après avoir recherché Markdown et Visual Studio, je viens de découvrir que si vous utilisez VS, vous pouvez installer Web Essentials et bénéficier du support Markdown 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 langue intégrée de GitHub est entièrement prise en charge par la prise en charge de `` ` syntaxe de langage.

enter image description here

  • Preview window => Voir une fenêtre de prévisualisation côte à côte du code HTML rendu
  • Compiler en HTML => Cliquez avec le bouton droit de la souris sur un fichier Markdown et sélectionnez Compiler Markdown en HTML. Cela générera un fichier .html imbriqué dans le fichier Markdown et restera synchronisé lorsque le fichier Markdown sera modifié.
  • 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 .

5
Leniel Maccaferri

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

Les demandes de validation et d'extraction, y compris les fichiers en prose, comportent désormais la source et les vues 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

4
VonC

À partir d’aujourd’hui, vous pouvez prévisualiser le fichier lorsque vous le modifiez.

enter image description here

1
Ruby

Une autre option - Atom, le nouvel éditeur de texte de Github, rendra un markdown à la github à mesure que vous le modifiez. Voir https://atom.io/

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

1
user2428107

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

  1. Possibilité de modifier hors ligne
  2. Pas seulement une réduction régulière, mais la réduction réelle à l'arôme 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.

Donc j'ai aliasé:

alias gm='gfms -a -p 8070'

L'utilisation de l'option -p Utilise l'API Github et utilise le CSS actuel de Github afin d'éviter toute surprise.

0
schimmy