Markdown sépare la source de la présentation
Un fichier Markdown est du texte ordinaire, généralement enregistré avec l'extension .md. La source reste compréhensible sans application particulière, tandis que GitHub, les outils de documentation, les générateurs de sites statiques et les éditeurs peuvent la restituer avec une mise en forme et une navigation.
Cette séparation est l'idée centrale : les auteurs décrivent le sens avec un petit vocabulaire, et la destination décide du rendu. Le même README peut être tout aussi lisible dans un terminal, lors d'une revue de code ou sur un site de documentation soigné.
# Deploying the API Run the **smoke tests** before release. - Verify health checks - Review error rates - Tag the build
Pourquoi Markdown convient bien à l'écriture technique
Markdown réduit au minimum la distance entre l'écriture et la relecture. La source contient peu de bruit visuel, les modifications produisent des diff utiles ligne par ligne et les fichiers peuvent vivre à côté du code ou de la configuration qu'ils expliquent.
- Portable : le texte brut n'est lié à aucun éditeur ni fournisseur.
- Differential : les modifications sont faciles à inspecter dans le contrôle de version.
- Composable : les outils de documentation peuvent le transformer en HTML, en PDF ou en contenu d'aide.
- Lisible : la source est utile même avant d'être rendue.
- Automatisable : les scripts peuvent vérifier les liens, les titres, les exemples et les conventions de style.
Markdown possède une syntaxe de base et plusieurs variantes
Le cœur commun couvre les paragraphes, les titres, l'emphase, les liens, les images, les citations, les listes et le code. Les plateformes ajoutent souvent des extensions. GitHub Flavored Markdown, par exemple, a popularisé les tableaux, les listes de tâches et le barré dans les flux de travail des développeurs.
Les extensions sont utiles, mais la portabilité reste importante. Un simple titre fonctionne presque partout ; un bloc de diagramme propre à une plateforme, peut-être pas. Lorsqu'un document doit circuler entre plusieurs outils, testez la syntaxe dans la destination et conservez le sens important dans du texte ordinaire.
Où trouve-t-on Markdown
Markdown est courant partout où le contenu doit rester proche du logiciel ou transiter par un flux de travail textuel. Il est également utile en dehors de l'ingénierie lorsqu'une source durable et simple à maintenir a plus de valeur qu'une mise en page précise.
- Les fichiers README, les guides de contribution, les changelogs et les notes de version
- Les références d'API, les tutoriels, les runbooks et les enregistrements de décisions d'architecture
- Les descriptions d'issues, les pull requests, les commentaires et les bases de connaissances d'équipe
- Les sites web statiques, les blogs, la documentation produit et les manuels internes
- Les notes ou documents convertis qui nécessitent un nettoyage avant publication
Ce que Markdown n'est pas conçu pour faire
Markdown n'est pas un format de mise en page. Les polices exactes, les colonnes, les objets flottants, la pagination imprimée et les composants interactifs complexes relèvent d'autres systèmes. Un PDF ou une présentation convertis préserveront plus facilement le texte utile que leur composition visuelle.
Il n'est pas non plus automatiquement sûr du simple fait qu'il s'agit de texte brut. Les moteurs de rendu doivent considérer les liens et l'éventuel HTML brut comme non fiables. Un bon éditeur assainit le rendu de l'aperçu et un pipeline de publication applique sa propre politique de sécurité.