Cet éditeur de README permet d’écrire des fichiers README.md avec un aperçu en direct façon GitHub, une table des matières cliquable, des listes de tâches, des tableaux et des blocs de code. Partez du README d’exemple, mettez en forme avec la barre d’outils ou les raccourcis, puis téléchargez le .md ou une page HTML autonome. Le brouillon s’enregistre dans le navigateur.
Mode d’emploi
- Écrivez du Markdown dans l’éditeur, ou déposez, ouvrez ou collez un fichier .md. Un README d’exemple est chargé pour démarrer.
- Utilisez la barre ou les raccourcis pour gras, italique, titres, liens, listes, tâches, code, citations et tableaux.
- Passez à Aperçu pour voir le rendu façon GitHub avec un sommaire cliquable, ou à HTML pour récupérer le code généré.
- Copiez le HTML, téléchargez une page .html autonome avec styles ou le fichier .md.
- Prend en charge le GitHub Flavored Markdown : tableaux, listes de tâches, blocs de code, texte barré et liens automatiques. Les titres reçoivent des ancres façon GitHub.
- Le HTML est assaini : scripts et attributs dangereux sont supprimés.
- Votre brouillon est enregistré automatiquement dans ce navigateur et vous attend à votre retour.
- Sur grand écran, Côte à côte affiche l’éditeur et l’aperçu ensemble.
Ce que contient un bon README
Le README est la première chose qu’on voit dans un dépôt : il doit répondre vite à trois questions, ce que fait le projet, comment l’installer et comment l’utiliser. Un ordre courant : une description d’une ligne, un court exemple ou une capture, l’installation, l’utilisation avec un bloc de code, la configuration, comment contribuer et la licence. Évitez le jargon dans le premier paragraphe ; les détails viennent ensuite.
Les blocs de code avec un nom de langage (```js, ```bash) sont colorés sur GitHub. Les liens relatifs comme docs/setup.md fonctionnent dans le dépôt, et les images peuvent pointer vers ses fichiers.
GitHub Flavored Markdown
L’aperçu suit le GitHub Flavored Markdown (GFM), une extension du standard CommonMark. En plus des titres, listes, liens et emphases, il ajoute les tableaux à barres verticales, les listes de tâches - [ ] et - [x], le ~~barré~~, les liens automatiques pour les URL nues et les blocs de code délimités. Chaque titre reçoit une ancre à la manière de GitHub : un lien #installation mène à cette section, ce qu’utilise la table des matières.
Questions fréquentes
Comment ajouter une table des matières à un README ?
Ajoutez une liste de liens vers les ancres de vos titres, par exemple - [Utilisation](#utilisation) ; GitHub les résout comme l’aperçu. La table des matières cliquable de l’aperçu montre chaque titre et son ancre.
Comment faire une liste de tâches ?
Commencez la ligne par - [ ] pour une tâche ouverte ou - [x] pour une tâche faite. Sur GitHub, les listes de tâches des issues et pull requests se cochent directement.
Les tableaux et blocs de code GitHub sont-ils pris en charge ?
Oui. Les tableaux utilisent | entre les colonnes et une ligne de tirets sous l’en-tête ; les blocs de code s’ouvrent et se ferment par trois accents graves.
Mon brouillon est-il enregistré ?
Oui, automatiquement dans ce navigateur, et il est toujours là à votre retour. Rien n’est envoyé.
Puis-je récupérer le HTML ?
Oui. Passez à la vue HTML pour copier le code généré et assaini, ou téléchargez une page .html autonome avec styles.