Eine Online-Markdown-Vorschau und ein lokaler Dokumenten-Build beantworten verschiedene Fragen. In einer Online-Vorschau wird gefragt: „Wird dieser Markdown in einer allgemeinen Vorschau sauber gerendert und gibt es offensichtliche Probleme bei der Erstellung?“ Ein lokaler Dokument-Build fragt: „Funktioniert dieser Inhalt in unserem tatsächlichen Dokumentationssystem?“
Beides ist nützlich. Der Fehler besteht darin, eine Schicht zu bitten, die Arbeit der anderen Schicht zu erledigen. Der Markdown Validator von Converty ist eine schnelle Frühprüfung. Ihr lokaler Dokumenten-Build bleibt die letzte Umgebungsprüfung, wenn es auf plattformspezifisches Rendering ankommt.
Nutzen Sie die Online-Vorschau für eine schnelle Überprüfung des Entwurfs
Eine Online-Markdown-Vorschau ist nützlich, wenn sich der Inhalt noch bewegt. Ein README-Abschnitt, ein Versionshinweis, ein Änderungsprotokolleintrag oder ein Supportdokument können überprüft werden, bevor daraus ein Pull Request oder ein Dokumentbuild wird.
Die Vorschau hilft dabei, Folgendes zu erkennen:
- kaputt aussehende Tische
- Probleme mit der Überschriftenstruktur
- Fehlender Alternativtext
- leere Links
- unbeschriftete Codezäune
- Roh-HTML, das überprüft werden muss
Dies ist die Phase, in der schnelles Feedback wichtiger ist als vollständige Umgebungsgenauigkeit.
Verwenden Sie für das endgültige Rendering einen lokalen Dokument-Build
Ein lokaler Dokumenten-Build ist die richtige Ebene, wenn die endgültige Plattform über benutzerdefiniertes Verhalten verfügt. Viele Dokumentsysteme transformieren Markdown durch Komponenten, Routing, Syntaxhervorhebung, benutzerdefinierte Callouts oder Framework-spezifisches Styling.
Nur der lokale Build kann zeigen, ob der Inhalt in dieser Umgebung funktioniert. Wenn eine Seite benutzerdefinierte Komponenten, importierte Snippets oder produktspezifisches Rendering verwendet, sollte die Browservorschau an erster Stelle und nicht an letzter Stelle stehen.
Der beste Workflow nutzt beides
Verwenden Sie die Online-Vorschau, um die Quelle zu bereinigen. Verwenden Sie den lokalen Build, um das Ziel zu überprüfen.
Diese Reihenfolge spart Zeit, da der lokale Build keine grundlegenden Markdown-Fehler mehr erkennt. Es kann sich auf das plattformspezifische Verhalten konzentrieren, das es auf einzigartige Weise testen kann.
Einen praktischen Arbeitsablauf für die frühzeitige Überprüfung finden Sie unter So zeigen Sie eine Vorschau von GitHub-Flavored Markdown an, bevor Sie es festlegen. Für Produkt- und Dokumentenübergaben lesen Sie Wie Produkt- und Dokumententeams Markdown überprüfen können, ohne die Formatierung zu verlieren.
Öffnen Sie den Markdown Validator, wenn Sie die schnelle Online-Vorschauebene benötigen, bevor Sie denselben Inhalt in einen lokalen Dokument-Build oder eine endgültige Veröffentlichungsvorschau verschieben.
