Docusaurus ist ein statischer Website-Generator, der hauptsächlich für die Erstellung von Dokumentationswebseiten verwendent wird. Docusaurus wird von Meta weiterentwickelt und ist unter der MIT-Lizenz veröffentlicht. Daher kann das Tool frei und kostenlos verwendet werden. Die Hauptmerkmale sind:

• Einfachheit: Dokumentation wird in Markdown geschrieben und Docussaurus wandelt sie in HTML-Dateien um.
• Reaktivität: Docusaurus verwendet React um interaktive Elemente hinzuzufügen. So können auch spezielle Markdown Files (MDX) React Elemente beinhalten.
• Erweiterbar: Durch eine modulare Architektur konnen benutzererstellte Plugins hinzugefügt werden.
• Versionierung und Lokalisierung: Eine Versionierung von Dokumentationen sowie mehrsprachige Inhalte werden von Haus aus unterstützt.

Inhalte Part I

Beispiele

Viele bekannte Webseiten benutzen Docusaurus, wie z.B. Ionic, Jest oder React. Einen Showcase gibt es auf der Docusaurus Homepage https://docusaurus.io/showcase.

Installieren und Projekt anlegen

Vorrausgesetzt wird das Node.js und npm installiert sind. In diesem Fall:

node -v
v22.9.0

Mithilfe des nachstehenden Kommandos lässt sich das Grundtemplate einrichten.t

npx create-docusaurus@latest example-docs classic --typescript
# oder alternativ mit pnpm
pnpm dlx create-docusaurus@latest example-docs classic --typescript

Damit erhält man die folgende Struktur:

Bereitstellen lässt sich die Dokumentation anschließend per „npm start“ für die Entwicklung. In weiterer Folge lässt sich alles an der Seite frei gestalten. So etwa Logos, Farbpalette, Styles, Footer, Header, Links, etc.

Bereinigen

Docusaurus ermöglicht es nicht nur mit Markdown Files Dokumentationen zu erstellen, sondern auch Webseiten mithilfe von React zu integrieren (üblicherweise die Startseite) oder einen Blog (z.B. Versionsänderungen) zu machen.

In unserem Beispiel beschränken wir uns auf die Dokumentationsfeatures und bereinigen dazu das Projekt. Das erfolgt in drei Schritten:

1. Löschen des Ordners „blog“
2. Entfernen der Blog-Referenzen im Docusaurus-Config-File
3. Anpassen der URL des Dokumentationseinstiegsfiles

Markdown schreiben

Im erstellten Template finden sich nun verschiedene Files:

„.md“-Files sind herkömmliche Markdown Files. „.mdx“-Files hingegen sind Markdown Files die angereichert sind mit React JSX Funktionalität. Diese Files enthalten die eigentliche Dokumentation. Als generelle Hilfe bei Markdown empfehle ich https://www.markdownguide.org/.  Im Header dieser Files lassen sich Optionen treffen, etwa wie der Titel des Dokuments in der Übersicht ist oder die URL. So haben wir vorher im ersten Video dem Intro die URL „/“ gegeben.

In jedem Ordner gibt es ein optionales „_category_.json“-File, welches uns die verwendete Bezeichung für eine Gruppe (= Ordner) von zusammengehörigen Dokumentationsseiten sowie die Position auf der Sidebar verändern lässt.

Wird im Markdown kein Header angegeben und in den Ordnern kein category json File angelegt, so wird standardmäßig der Name des Files bzw. Ordnerns herangezogen.

Außerdem finden sich einige Bilder im img Order. Es ist optional ob Dokumente wie Bilder, PDF, etc. im zugehörigen Ordner angelegt werden oder im static Folder.

Als Beispiel wird eine neues File angelegt, welches unter dem Adresszustatz „/example“ erreicht werden kann, als Titel Beispiel trägt und einige Überschriften sowie anderen Inhalt enhält.

Build & Plugins – Suchfeld erstellen

Es gibt unterschiedliche Varianten ein Suchfeld zu erstellen. Auf Webseiten mit OpenSource Bezug empfiehlt sich Algolia. Wir haben aber nur ein privates Projekt und installieren uns dazu ein anderes Plugin via:

npm i @easyops-cn/docusaurus-search-local
# oder alternativ wieder via pnpm
pnpm i @easyops-cn/docusaurus-search-local

Die Suche ist erst möglich nach einem Build. Daher adden wir das Plugin und führen die folgenden Schritte aus:

1. Hinzufügen des Plugins/Themes im Config File
2. Docusaurus Build
3. Docusaurus Serve

Den Fehler ingnorieren wir an dieser Stelle einmal, da er nicht mehr auftreten sollte, wenn alle Links korrekt sind.

Abschluss Part I

Mit Docusaurus lassen sich echt einfach und schnell professionelle Dokumentationswebseiten erstellen. In diesem ersten Teil wurde ein Grundprojekt angelegt, dieses bereinigt auf die Dokumentationsfeatures, ein Markdown File erstellt und eine Erweiterung in Form eines Suchfeldes hinzugefügt. Eventuell gibt es in weiteren Teilen: Lokalisierung; Versionierung und Bereitstellen via GitHub Pages.

* Titelbild von https://repository-images.githubusercontent.com/94911145/de889380-2905-11eb-9e9b-9332f0537e38