Umstellung von Markdown auf AsciiDoc
Von Ronald Keschke
In diesem Beitrag möchte ich eine kürzlich durchgeführte Umstellung in unserem Projekt dokumentieren: den Wechsel von Markdown zu AsciiDoc für alle unsere Inhalte. Bisher hatten wir genau einen Blogpost in Markdown verfasst, aber aus verschiedenen Gründen haben wir uns entschieden, zu AsciiDoc überzugehen. Hier teile ich unsere Beweggründe, den Prozess und die gewonnenen Erkenntnisse.
Warum AsciiDoc?
AsciiDoc bietet gegenüber Markdown einige Vorteile, die für unser Projekt besonders relevant waren:
-
Mehr Strukturierungsmöglichkeiten: AsciiDoc erlaubt eine feinere Gliederung von Dokumenten, einschließlich Anhängen, Indizes und Glossaren.
-
Erweiterte Formatierungsoptionen: Während Markdown in seinen Formatierungsmöglichkeiten eher beschränkt ist, bietet AsciiDoc eine breite Palette an Gestaltungsmöglichkeiten, wie Admonitions (Hinweisboxen), Seitenumbrüche und benutzerdefinierte Attribute.
-
Bessere Unterstützung für technische Dokumentation: AsciiDoc wurde speziell für die Erstellung von technischen Dokumentationen entwickelt, was es ideal für unser Projekt machte, das eine detaillierte Dokumentation beinhaltet.
Der Umstellungsprozess
Die Umstellung begann mit der Konvertierung unseres einzigen Markdown-Posts in AsciiDoc. Hierbei haben wir folgende Schritte durchgeführt:
-
Analyse des bestehenden Markdown-Dokuments: Zunächst haben wir die Struktur und die spezifischen Formatierungen unseres Markdown-Dokuments analysiert, um einen Überblick darüber zu bekommen, welche AsciiDoc-Features wir nutzen könnten.
-
Manuelle Konvertierung und Anpassung: Da wir nur einen Post zu konvertieren hatten, entschieden wir uns für eine manuelle Überführung, um die Kontrolle über die Formatierung und Struktur zu behalten. Während der Konvertierung haben wir spezifische AsciiDoc-Features genutzt, um die Lesbarkeit und Struktur des Dokuments zu verbessern.
-
Überprüfung und Feinabstimmung: Nach der ersten Konvertierung haben wir das Ergebnis sorgfältig überprüft und Feinabstimmungen vorgenommen, um sicherzustellen, dass alle Informationen korrekt übertragen wurden und das Layout unseren Vorstellungen entspricht.
Erkenntnisse aus der Umstellung
Die Umstellung hat uns einige wertvolle Erkenntnisse geliefert:
-
AsciiDoc erfordert eine Einarbeitungszeit: Obwohl AsciiDoc mächtiger als Markdown ist, erfordert es eine gewisse Einarbeitungszeit, insbesondere wenn es um die Nutzung fortgeschrittener Features geht.
-
Automatisierte Tools können hilfreich sein: Für größere Projekte könnte die Nutzung automatisierter Konvertierungstools eine erhebliche Zeitersparnis bedeuten. Für unser kleines Projekt war die manuelle Konvertierung machbar, aber wir planen, in Zukunft Tools zu erkunden.
-
Die Investition kann sich lohnen: Die zusätzlichen Möglichkeiten von AsciiDoc, insbesondere für technische Dokumentationen, rechtfertigen die Umstellung und den damit verbundenen Aufwand.
Mein Fazit
Die Entscheidung, von Markdown zu AsciiDoc zu wechseln, war für unser Projekt eine bedeutsame, und die bisherigen Ergebnisse bestätigen unsere Entscheidung. Die erweiterten Funktionen von AsciiDoc bieten uns die Flexibilität und die Möglichkeiten, die wir für die Darstellung unseres Inhalts benötigen. Wir sind gespannt darauf, wie sich unsere Dokumentation und unsere Blogposts weiterentwickeln werden, jetzt, wo wir die Vorteile von AsciiDoc voll ausschöpfen können