L'aperçu Markdown en ligne et la création de documents locaux répondent à différentes questions. Un aperçu en ligne demande : « Ce Markdown s'affiche-t-il proprement dans un aperçu général et y a-t-il des problèmes de création évidents ? » Une version de documentation locale demande : « Ce contenu fonctionne-t-il dans notre système de documentation actuel ? »
Les deux sont utiles. L'erreur est de demander à une couche de faire le travail de l'autre couche. Le Markdown Validator de Converty est une vérification anticipée rapide. La version de votre documentation locale reste la vérification finale de l'environnement lorsque le rendu spécifique à la plate-forme est important.
Utilisez l'aperçu en ligne pour une révision rapide des brouillons
Un aperçu Markdown en ligne est utile lorsque le contenu est toujours en mouvement. Une section README, une note de version, une entrée du journal des modifications ou un document de support peuvent être vérifiés avant qu'ils ne deviennent une demande d'extraction ou une construction de documents.
L'aperçu permet de détecter :
- des tables cassées
- problèmes de structure des titres
- texte alternatif manquant
- liens vides
- clôtures de code sans étiquette
- HTML brut qui doit être révisé
C’est l’étape où un retour rapide compte plus que la précision totale de l’environnement.
Utilisez une version de documentation locale pour le rendu final
Une version de documentation locale constitue la bonne couche lorsque la plate-forme finale a un comportement personnalisé. De nombreux systèmes de documentation transforment Markdown via des composants, un routage, une coloration syntaxique, des légendes personnalisées ou un style spécifique au framework.
Seule la version locale peut montrer si le contenu fonctionne dans cet environnement. Si une page utilise des composants personnalisés, des extraits importés ou un rendu spécifique au produit, l'aperçu du navigateur doit venir en premier et non en dernier.
Le meilleur workflow utilise les deux
Utilisez l'aperçu en ligne pour nettoyer la source. Utilisez la version locale pour vérifier la destination.
Cette séquence permet de gagner du temps car la version locale ne détecte plus les erreurs de base de Markdown. Il peut se concentrer sur le comportement spécifique à la plate-forme qu’il est seul à pouvoir tester.
Pour un flux de travail pratique de révision précoce, lisez Comment prévisualiser GitHub-Flavored Markdown avant de le valider. Pour les transferts de produits et de documents, lisez Comment les équipes produit et documents peuvent examiner le Markdown sans perdre le formatage.
Ouvrez le Markdown Validator lorsque vous avez besoin de la couche d'aperçu en ligne rapide avant de déplacer le même contenu dans une version de documentation locale ou un aperçu de publication final.
