Alles auf Markdown: Mozilla-Dokumentation legt HTML ad acta

Die offizielle Entwicklerdokumentation der Mozilla Foundation ist auf Markdown umgestiegen. Alle manuell verfassten Dokumente seien bereits in Markdown umgewandelt, ist einem Blogbeitrag zur "100 Percent Markdown Experience" zu entnehmen.

Das MDN in "MDN Web Docs", wie die Dokumentation heißt, steht für das vormalige Mozilla Developer Network und Mozilla Developer Center. Sie umfasst alle Dokumente der Mozilla Foundation für Webtechnologien, Open Web und laufende Mozilla-Projekte und existiert seit 2005. Geschrieben ist sie in React, SCSS, JSC, JavaScript und Python. Die händisch angelegten Dokumente waren bislang überwiegend in HTML verfasst – das ist ab jetzt Geschichte.

Wieso die Mozilla-Community sich den Berg Arbeit zugemutet hat, die Dokumentation mitsamt ihrem Quellcode umzuschreiben, erklärt ein Beitrag des südafrikanischen Entwicklers Schalk Neethling im Blog "Mozilla Hacks". Neethling ist Staff Community Manager bei MDN Web Docs und hatte das Konvertierungsprojekt koordiniert. Die Entscheidung für den Wechsel zu Markdown war ihm zufolge bereits im Juni 2021 gefallen.

Wieso Markdown bei Mozilla?

Dem Team zufolge ist Markdown zugänglicher und nutzerfreundlicher als HTML, um etwas zur Dokumentation beizutragen. Durch die Vereinheitlichung zu Markdown sollen Developer in allen Sprachen und Repositories auf einheitliche Weise mitmachen können. Das MDN-Entwicklungsteam kann bei Vorliegen aller Inhalte im Markdownformat den Code offenbar leichter bereinigen. Insgesamt gebe es damit weniger Code zu warten, was die Arbeitsabläufe bei den Beiträgen vereinfache. Zudem gelten ab jetzt für alle aktiven Sprachen die gleichen Linting-Regeln.

Der Mozilla-Hack-Beitrag listet alle Tools und Möglichkeiten auf, um an der Dokumentation mitzuwirken. Interessierte benötigen Zugriff auf eine Reihe von Tools wie Git, GitHub und Node.js. Der Post erklärt auch in einfachen Schritten, wie Entwicklerinnen und Entwickler ihre Beiträge zu Markdown konvertieren können. Drei Repositories stellen Code und Inhalt für das Projekt bereit, konkret die Verzeichnisse Markdown, Content und Translated Content bei GitHub.

Forken und Clonen der Repositories

Wer etwas beitragen mag, forkt das Translated-Content-Repository und zieht von den anderen beiden einen Klon. Das geht mit folgender Eingabe im Command Line Interface (CLI) von GitHub:

gh repo clone mdn/markdown
gh repo clone mdn/content
gh repo clone username/translated-content # replace username with your GitHub username

Mit dem Befehl cd markdown; yarn lässt sich das Konvertierungstool installieren, und es gilt, im Root-Verzeichnis eine neue Datei namens .env anzulegen mit folgendem Inhalt: CONTENT_TRANSLATED_ROOT=../translated-content/files. Abschließend lässt sich das Content-Repository einrichten durch folgende Eingabe:

cd .. # This moves you out of the `markdown` folder
cd content
yarn

Bereit zum Konvertieren in Markdown

Ab hier ist alles bereit für das Konvertieren in Markdown, wozu eine detaillierte Dokumentation im GitHub-Repo hinterlegt ist. In einem Google-Sheet hat das Team eine Liste von Dokumenten angelegt, die noch auf eine Umwandlung in Markdown warten. Für jede Zielsprache existiert ein eigenes Sheet. Zum Konvertieren ist es laut Team nicht nötig, die Sprache zu beherrschen. Ein Verständnis von Markdown und Grundlagen in HTML sollen dafür ausreichen.

Alle weiteren Schritte vom Anlegen eines Issues über das Aktualisieren von Kalkulationstabellen, das Anlegen von Feature-Zweigen, das Ausführen der Konvertierung und das Testen von Änderungen sind ausführlich in Neethlings Blogeintrag beschrieben. Wie sich Pull Requests vorbereiten und öffnen lassen, ist darin ebenfalls erklärt.

Mitmachen, wer mag

Das Team der Mozilla-Dokumentation MDN Web Docs sucht dem Blogeintrag zufolge neue Mitstreiter, die das Markdownprojekt unterstützen.

(sih)