Dokumentationsseiten mit Docusaurus erstellen

Sie benötigen eine Dokumentationsseite für Ihre Bibliothek, Ihr Framework oder Ihr SaaS-Produkt. Sie möchten, dass sie statisch, schnell und wartbar ist, ohne alles von Grund auf neu zu erstellen. Docusaurus v3 bewältigt dies gut – es ist ein ausgereifter React-basierter Static-Site-Generator, der Versionierung, Suchintegration und MDX-Unterstützung von Haus aus mitbringt.

Dieser Leitfaden behandelt die Architektur und praktische Einrichtung einer Docusaurus-Dokumentationsseite und konzentriert sich auf Konzepte, die über Minor-Releases hinweg stabil bleiben.

Kernarchitektur einer Docusaurus-Dokumentationsseite

Docusaurus organisiert Inhalte in drei verschiedene Content-Typen:

Docs befinden sich im Verzeichnis /docs. Dies sind Ihre primären Dokumentationsseiten, die mit automatischer Sidebar-Navigation und Versionierungsunterstützung gerendert werden. Jede Markdown- oder MDX-Datei wird zu einer Seite.

Blog-Posts befinden sich in /blog. Diese eignen sich gut für Changelogs, Release-Ankündigungen oder Tutorials, die zeitkritisch sind.

Pages in /src/pages sind eigenständige React-Komponenten oder MDX-Dateien für benutzerdefinierte Landing-Pages, About-Bereiche oder alles außerhalb der Docs/Blog-Struktur.

Das Sidebar- und Versionierungsmodell verdient Aufmerksamkeit. Docusaurus generiert automatisch Sidebars aus Ihrer Ordnerstruktur, oder Sie können sie explizit in sidebars.js definieren. Wenn Sie eine Version erstellen, wird ein Snapshot Ihrer aktuellen Docs in versioned_docs/ gespeichert, sodass Benutzer auf Dokumentation für ältere Releases zugreifen können.

Docusaurus v3 Setup: Erste Schritte

Modernes Scaffolding unterstützt npm, Yarn, pnpm und Bun. Wählen Sie, was Ihr Team verwendet:

npx create-docusaurus@latest my-docs classic

Das classic-Preset bündelt das Docs-Plugin, Blog-Plugin und Standard-Theme – ausreichend für die meisten Entwicklerdokumentationsseiten. Docusaurus v3 erfordert Node.js 20 oder höher für lokale Entwicklung und CI.

Nach dem Scaffolding sieht Ihre Projektstruktur so aus:

my-docs/
├── docs/
├── blog/
├── src/
│   ├── components/
│   ├── css/
│   └── pages/
├── static/
├── docusaurus.config.js
└── sidebars.js

Die Datei docusaurus.config.js steuert Site-Metadaten, Theme-Konfiguration, Navbar, Footer und Plugin-Optionen. Diese einzelne Datei übernimmt die meisten Anpassungen, ohne React-Code anzufassen.

MDX-Dokumentation: Inhalte schreiben

Docusaurus v3 verwendet MDX v3, das strenger ist als frühere Versionen. Dies ist wichtig, wenn Sie von v2 migrieren – MDX v3 erzwingt korrekte JSX-Syntax und ignoriert fehlerhafte Komponenten nicht stillschweigend.

Jede Doc-Datei unterstützt Frontmatter für Metadaten:

---
id: getting-started
title: Getting Started
sidebar_position: 1
---

# Getting Started

Your content here. You can import React components directly.

Sie können React-Komponenten einbetten, Mermaid-Diagramme verwenden und interaktive Code-Blöcke einbinden. Der Alias @site verweist auf Ihr Projektstammverzeichnis für Imports.

Für Diagramme aktivieren Sie das Mermaid-Plugin in Ihrer Konfiguration:

// docusaurus.config.js
module.exports = {
  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],
}

Theming und Anpassung

Das Plugin-System ermöglicht es Ihnen, Funktionalität zu erweitern, ohne das Theme zu forken. Gängige Plugins verarbeiten Analytics, Sitemaps, PWA-Unterstützung und Redirects.

Für visuelle Anpassungen überschreiben Sie CSS-Variablen in src/css/custom.css. Das Theme verwendet Infima unter der Haube, sodass Sie Design-Tokens anpassen, anstatt Komponenten-Styles zu schreiben:

:root {
  --ifm-color-primary: #2e8555;
  --ifm-code-font-size: 95%;
}

Tiefere Anpassungen verwenden „Swizzling” – das Auswerfen von Theme-Komponenten, um sie zu modifizieren. Führen Sie npx docusaurus swizzle aus, um verfügbare Komponenten zu sehen. Swizzlen Sie nur, was Sie benötigen, da ausgeworfene Komponenten manuelle Updates beim Upgrade von Docusaurus erfordern.

Such-Integration

Die meisten Produktions-Docusaurus-Seiten verwenden Algolia DocSearch. Bewerben Sie sich für das kostenlose Programm, wenn Ihre Docs öffentlich sind, oder hosten Sie den Crawler selbst für private Dokumentation.

Die Konfiguration befindet sich in themeConfig:

// docusaurus.config.js
module.exports = {
  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
    },
  },
}

DocSearch v4 unterstützt auch Algolia AskAI, das eine optionale konversationelle Suche zusätzlich zur Standard-Sucherfahrung hinzufügt und als Teil derselben Algolia-Integration konfiguriert wird.

Deployment

Docusaurus erstellt statisches HTML, CSS und JavaScript im Verzeichnis /build. Jedes statische Hosting funktioniert: Vercel, Netlify, GitHub Pages, Cloudflare Pages oder Ihr eigenes CDN.

npm run build

Die Ausgabe ist eine Standard-Static-Site ohne erforderliche Server-Runtime. Konfigurieren Sie Ihren Hosting-Anbieter so, dass er Client-seitiges Routing verarbeitet, indem er index.html für unbekannte Pfade bereitstellt.

Was Sie für die Produktion wissen sollten

Ein paar praktische Hinweise zur Wartung einer Entwicklerdokumentationsseite:

• Versionierung erhöht die Komplexität. Versionieren Sie nur, wenn Benutzer wirklich Zugriff auf alte Docs benötigen. Viele Projekte kommen gut mit einer einzigen „aktuellen” Version aus.
• MDX-Strenge fängt echte Bugs ab. Wenn die Migration von v2 Seiten beschädigt, weisen die Fehler normalerweise auf tatsächliche JSX-Probleme hin, die es wert sind, behoben zu werden.
• Build-Zeiten skalieren mit Inhalten. Große Sites profitieren von inkrementellen Builds in CI und Caching von node_modules.

Fazit

Docusaurus übernimmt die Infrastruktur, sodass Sie sich auf das Schreiben guter Dokumentation konzentrieren können. Die React-Grundlage bedeutet, dass Frontend-Teams bei Bedarf tiefgreifend anpassen können, während die Standardeinstellungen gut genug funktionieren, dass viele Sites ohne Berührung von React-Code ausgeliefert werden. Beginnen Sie mit dem Classic-Preset, fügen Sie Plugins hinzu, wenn Anforderungen entstehen, und widerstehen Sie dem Drang, zu viel anzupassen, bevor Ihr Dokumentationsinhalt solide ist.

FAQs

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.