Zum Hauptinhalt springen

Einführung

docStatic ist eine moderne Dokumentationsplattform, die die Kluft zwischen Autoren und Entwicklern überbrückt und Ihnen dabei hilft, Online-Dokumentationen zu erstellen, die Ihre Nutzer begeistern werden.

Sie vereint die besten Funktionen von Komponenten-Content-Management-Systemen und Docs-as-Code-Lösungen für Online-Dokumentation. Mit docStatic kann jeder in Ihrem Team Ihre Dokumente erstellen und bearbeiten, ohne den Arbeitsablauf Ihrer Entwickler zu beeinträchtigen.

Funktionen​

docStatic begann als Weiterentwicklung von Tinasaurus, einem Open-Source-Projekt auf Basis von React, das einen Statik-Site-Generator (Docusaurus) mit einem Headless-Content-Management-System (TinaCMS). Es umfasst:

  • Eine benutzerfreundliche Bearbeitungsoberfläche für Markdown-, MDX-, JSON- und YAML-Inhalte.
  • Integration in bestehende Git- und CI/CD-Workflows.
  • Eingebettete MDX-Komponenten für die Erstellung reichhaltiger Inhalte.
  • Medienmanager mit Unterstützung für Medienanbieter von Drittanbietern.
  • Bearbeitung in der Cloud (keine lokale Einrichtung erforderlich).
  • Dashboards mit Berichten zum Inhaltsstatus und zur Linkintegrität.
  • Model Context Protocol (MCP)-Server für die Integration von KI-Assistenten.
  • Optionaler browserbasierter KI-Chatbot zur Beantwortung von Fragen zur Dokumentation.

Einfache Inhaltsverwaltung​

Die Standard-Sammlungen von docStatic umfassen einige der fortgeschritteneren Erstellungsfunktionen, die man von einem CCMS erwarten würde.

Der Rich-Text-Editor erleichtert das Hinzufügen von:

  • Bedingtem Text, Snippets, Variablensätzen und zentral verwalteten URLs zur Wiederverwendung von Inhalten.
  • Taxonomien.
  • Glossarbegriffen.
  • Code-Blöcken, Kommentaren, ausblendbaren Details, Abbildungen, Fußnoten und Registerkarten. Diese stehen als Vorlagen zur Verfügung, die Sie in eine Inhaltsdatei einfügen können.

Das CMS verwendet ein GraphQL-Schema, um die Struktur Ihrer Inhalte als eine Reihe von Sammlungen zu beschreiben.

Dashboards​

docStatic fügt TinaCMS Dashboard-Funktionen hinzu und fragt die GraphQL-API ab, um direkt im CMS über den Inhaltsstatus und die Linkintegrität zu berichten. Dazu gehört eine Inhaltsübersicht, die den Workflow-Status jedes Themas anzeigt, sowie ein Link-Integritäts-Dashboard, das externe Links prüft und defekte Links markiert.

Git-gestützt​

Versionskontrolle, Automatisierung und optional die Veröffentlichung werden über GitHub verwaltet. Beim Bearbeiten von Dateien mit dem Rich-Text-Editor führt TinaCMS beim Speichern entweder einen Commit durch oder speichert direkt in die Datei, wenn lokal gearbeitet wird. Git bleibt die zentrale Informationsquelle für das gesamte Team.

Die Repository-Struktur ähnelt stark den Docusaurus-Standardeinstellungen, weist jedoch einige Änderungen auf, die für die Integration mit TinaCMS erforderlich sind.

Vorkonfigurierte Plugins​

docStatic ist mit Plugins vorkonfiguriert, die Funktionen wie KaTeX-Gleichungen, die Lunr-Suche, Mermaid-Diagramme und OpenAPI-Dokumentation. Es gibt eine integrierte Unterstützung für die Internationalisierung (i18n). Mehrsprachige Rechtschreib-, Grammatik- und optional auch Stilprüfungen werden von LanguageTool über Browser- und IDE-Plugins bereitgestellt.

KI-Integration​

docStatic enthält einen integrierten Model Context Protocol (MCP)-Server, der es KI-Assistenten ermöglicht, direkt auf Ihre Dokumentation zuzugreifen und diese zu verstehen. Dies bietet intelligente Unterstützung bei der Bearbeitung, Suche und Analyse von Inhalten auf der Grundlage Ihrer tatsächlichen Dokumentationsstruktur und -inhalte.

docStatic kann Ihrer veröffentlichten Website außerdem einen optionalen KI-Chatbot hinzufügen, sodass Besucher Fragen stellen und Antworten erhalten können, die auf Ihrer Dokumentation basieren. Standardmäßig läuft er vollständig im Browser des Besuchers – kein externer Dienst, API-Schlüssel oder Server erforderlich – er kann aber auch auf einen kostenpflichtigen, selbst gehosteten Anbieter verweisen.

React-basiert​

Inhalte werden im MDX-Format gespeichert – einer Erweiterung von Markdown, die benutzerdefinierte React-Komponenten für Funktionen wie z. B. Warnhinweise unterstützt. Diese Komponenten sind universell verfügbar und müssen nicht in einzelnen Dateien deklariert werden. Bei der lokalen Arbeit kompiliert der Dev-Server die Seiten sofort neu, sobald Sie Ihre Änderungen speichern.

Vollständig dokumentiert​

Entwickler finden alle Informationen, die sie zur Konfiguration und ersten Nutzung von docStatic benötigen, in der Dokumentation zu Docusaurus und TinaCMS. Diese Informationen werden hier nicht wiederholt, um zu vermeiden, dass sie möglicherweise veraltet sind. Stattdessen konzentriert sich die docStatic-Dokumentation auf die Nutzung des CMS.