Zum Hauptinhalt springen

Installation

Willkommen! Diese Anleitung führt Sie durch die erstmalige Einrichtung von docStatic.

Falls Sie noch nie mit GitHub oder „Docs-as-Code“ gearbeitet haben, machen Sie sich keine Sorgen – wir erklären Ihnen, was erforderlich ist, warum und wo Sie weitere Informationen finden.

Voraussetzungen​

Sie können docStatic lokal (auf Ihrem Computer) ausführen oder in der Cloud hosten.

Für die einfachste Cloud-Einrichtung erstellen Sie kostenlose Konten bei diesen Diensten:

  • GitHub – speichert Ihre Inhalte und verfolgt Änderungen
  • TinaCMS – ermöglicht die Bearbeitung über den Browser
  • LanguageTool – bietet eine optionale Grammatik- und Stilprüfung

Wenn Sie docStatic stattdessen lokal (auf Ihrem Computer) ausführen möchten, lesen Sie bitte die Anforderungen für die lokale Entwicklung.

Anforderungen für die lokale Entwicklung​

Dieser Abschnitt gilt nur, wenn Sie lokal arbeiten möchten.

Sie benötigen eine integrierte Entwicklungsumgebung (IDE) oder einen Texteditor. Zwei Open-Source-Optionen sind:

Außerdem müssen Sie Node.js für die Build-Tools und Yarn für die Paketverwaltung installieren.

Node.js installieren​

Sie müssen Node.js in der Version 22.0 oder höher installieren.

Überprüfen Sie, ob Node.js bereits installiert ist. Öffnen Sie ein Terminal (Eingabeaufforderung oder Terminal-App) und führen Sie folgenden Befehl aus:

node -v

Wenn eine Versionsnummer angezeigt wird, die mit v22 oder höher beginnt, können Sie loslegen.

Falls Node.js nicht installiert ist oder Sie eine ältere Version haben:

  1. Rufen Sie die Seite mit den offiziellen Node.js-Downloads auf.
  2. Wählen Sie die LTS-Version (Long-Term Support) für Ihr Betriebssystem aus. Das Installationsprogramm enthält npm, den Node Package Manager, den Sie in späteren Schritten benötigen. Während der Installation:* Behalten Sie die Standardoptionen bei (diese umfassen die erforderlichen Abhängigkeiten) * Schließen Sie das Terminal nach Abschluss der Installation und öffnen Sie es erneut.
  3. (Optional) Wenn du an verschiedenen Projekten arbeitest, die unterschiedliche Node-Versionen erfordern, installiere nvm (Node Version Manager). Mit nvm kannst du zwischen verschiedenen Node-Versionen wechseln, ohne deine Konfiguration zu beeinträchtigen.

Yarn installieren​

docStatic verwendet Yarn für die Paketverwaltung.

Überprüfen Sie, ob Yarn bereits installiert ist. Öffnen Sie Ihr Terminal oder die Eingabeaufforderung und geben Sie Folgendes ein:

yarn -v

Wenn eine Versionsnummer angezeigt wird, ist Yarn bereits installiert.

Wenn Sie die Meldung „Befehl nicht gefunden“ oder einen ähnlichen Fehler erhalten, öffnen Sie ein Terminal (Eingabeaufforderung oder Terminal-App) und führen Sie Folgendes aus:

npm install -g yarn
Hinweis

Unter macOS oder Linux müssen Sie dem Befehl möglicherweise „sudo“ voranstellen, um die erforderlichen Berechtigungen zu erteilen:

sudo npm install -g yarn
Note

On Windows, you don’t use sudo. Just open your terminal as Administrator and run the command.

docStatic herunterladen​

Es gibt zwei Möglichkeiten, eine eigene Kopie von docStatic zu erhalten:

  1. Erstelle eine neue Website mit `create-docstatic` (empfohlen). Mit einem einzigen Befehl erhältst du eine brandneue, eigenständige Website mit eigenem Namen und eigener Git-Historie.
  2. Fork und klone das Repository. Wählen Sie diese Option, wenn Sie zu docStatic selbst beitragen möchten oder es vorziehen, Aktualisierungen durch Zusammenführen mit Git zu verwalten.

Eine neue Website erstellen​

Öffnen Sie ein Terminal (Eingabeaufforderung oder Terminal-App) und führen Sie je nach Ihrem bevorzugten Paketmanager einen der folgenden Befehle aus. Ersetzen Sie my-docs durch den Namen Ihres Projekts.

npx create-docstatic@latest my-docs

Der Befehl lädt die neueste docStatic-Vorlage herunter, erstellt den Ordner my-docs, wandelt ihn in ein Git-Repository um und installiert die Projektabhängigkeiten. Starten Sie nach Abschluss des Vorgangs den lokalen Entwicklungsserver:

cd my-docs
yarn dev
Tip

Run npx create-docstatic@latest --help to see the available options, such as --no-install to skip dependency installation.

Wenn Sie Ihre Website auf diese Weise erstellt haben, können Sie direkt zum Abschnitt Projektstruktur springen.

Halten Sie Ihre Website auf dem neuesten Stand​

Wenn eine neue Version von docStatic veröffentlicht wird, führen Sie diesen Befehl im Stammverzeichnis Ihrer Website aus:

npx create-docstatic@latest --update

Der Befehl aktualisiert die docStatic-eigenen Dateien (React-Komponenten, Build-Skripte, Docusaurus- und Tina-Konfiguration, Versionen der Abhängigkeiten) und lässt Ihre Inhalte – docs/, blog/, config/, reuse/ und static/ – unberührt. Der Name Ihrer Website und alle von Ihnen hinzugefügten benutzerdefinierten package.json-Skripte bleiben erhalten.

Für die Aktualisierung ist ein sauberer Git-Arbeitsbaum erforderlich. Führen Sie daher zunächst einen Commit Ihrer Arbeit durch. Überprüfen Sie anschließend das Ergebnis mit git diff, wenden Sie alle Anpassungen, die Sie an den aktualisierten Dateien vorgenommen haben, erneut an und führen Sie einen Commit durch.

Tip

Add --dry-run to see what would change without writing anything.

Das docStatic-Repository forken​

Das Forken und Klonen ist die richtige Wahl, wenn du vorhast, zu docStatic beizutragen, oder wenn du zukünftige docStatic-Veröffentlichungen lieber mit Git in deine Website einbinden möchtest.

  1. Melde dich bei deinem GitHub-Konto an.
  2. Rufe https://github.com/aowendev/docstatic auf.
  3. Klicke auf „Fork“ (normalerweise oben rechts).
  4. Behalte den Standardnamen des Repositorys bei.
  5. Geben Sie eine Beschreibung Ihres Projekts ein.
  6. Stellen Sie sicher, dass „Nur den Hauptzweig kopieren“ aktiviert ist.
  7. Klicken Sie auf „Fork erstellen“.

GitHub erstellt einen neuen Zweig des Repositorys in Ihrem GitHub-Konto.

Klonen Sie Ihren Fork des „docStatic“-Repositorys​

So erstellen Sie einen Klon:

  1. Melden Sie sich bei Ihrem GitHub-Konto an.
  2. Navigieren Sie zum Repository des Forks.
  3. Klicken Sie auf das Repository, um es zu öffnen.
  4. Klicken Sie auf <> Code und kopieren Sie anschließend die URL.
  5. Öffnen Sie Ihr Terminal oder die Eingabeaufforderung und navigieren Sie mit cd zu dem Verzeichnis, in dem Sie den Klon speichern möchten. Zum Beispiel: cd Dokumente/Projekte/.
  6. Geben Sie git clone gefolgt von der URL Ihres Klons ein.
git clone https://github.com/acme-projects/docstatic.git

Projektabhängigkeiten installieren​

Dieser Schritt gilt nur, wenn Sie das Repository geforkt und geklont haben – create-docstatic installiert die Abhängigkeiten für Sie.

Navigieren Sie mit cd in den Stammordner Ihres geklonten docStatic-Repositorys und installieren Sie die Pakete:

cd docstatic
yarn install

Yarn lädt alles herunter, was in package.json aufgeführt ist. Dies kann einige Minuten dauern.

Projektstruktur​

Nachdem Sie Ihre Website erstellt oder das Repository geklont haben, sehen Sie verschiedene Dateien in Ihrem Projektordner. Im Folgenden haben wir einige der Dateien und Ordner der Projektstruktur aufgeführt, die Sie kennen sollten. Es handelt sich nicht um eine vollständige Liste aller Elemente im Projekt.

docstatic
├── apis
│   └── petstore.yaml
├── blog
│   └── hybrid.mdx
├── config
│   ├── docusaurus
│   │   └── index.json
│   ├── homepage
│   │   └── index.json
│   └── sidebar
│       └── index.json
│
├── docs
│   └── introduction.mdx
├── i18n
│   └── fr
├── mcp-server
│   └── src
│       └── server.ts
├── reuse
│   ├── code
│   │   └── example.xml
│   ├── conditions
│   │   └── index.json
│   ├── glossaryTerms
│   │   └── index.json
│   ├── snippets
│   │   └── example.mdx
│   ├── taxonomy
│   │   └── index.json
│   ├── variableSets
│   │   └── index.json
│   ├── code-files.json
│   └── snippets-files.json
├── scripts
│   └── generate-media-index.js
├── src
│   ├── css
│   │   └── custom.css
│   └── pages
│       ├── example-page.mdx
│       ├── index.js
│       └── index.module.css
├── static
│   └── img
├── tina
│   └── config.jsx
├── docusaurus.config.ts
├── package.json
├── README.md
├── sidebars.ts
└── yarn.lock

Überblick über die Projektstruktur​

  • /apis/ – OpenAPI-YAML-Dateien.
  • /blog/ – MDX-Dateien für den Blog.
  • /config/ – JSON-Dateien, die von TinaCMS zur Konfiguration von docStatic verwendet werden.
  • /docs/ – MDX-Dateien für die Dokumentation.
  • /i18n/ – Übersetzungsdateien.
  • /mcp-server/ – Der MCP-Server, der KI-Assistenten Zugriff auf Ihre Dokumentation gewährt.
  • /reuse/ – Wiederverwendbare Inhalte.
  • /scripts/ – Skripte für die Build-Phase, die automatisch von prebuild und predev ausgeführt werden.
  • /src/ – Nicht zur Dokumentation gehörende Dateien wie Seiten oder benutzerdefinierte React-Komponenten.
    • /src/pages – Alle JSX-/TSX-/MDX-Dateien in diesem Verzeichnis werden in eine Webseite umgewandelt.
  • /static/ – Statischer Ordner. Alle hier enthaltenen Inhalte werden in das Stammverzeichnis des endgültigen Build-Ordners kopiert.
  • /tina/ – TinaCMS-Konfiguration und GraphQL-Schema.
  • /docusaurus.config.ts – Eine Konfigurationsdatei mit den Einstellungen für die Website.
  • /package.json – Eine docStatic-Website ist eine React-App. Sie können beliebige npm-Pakete installieren und verwenden.
  • /sidebars.ts – Legt die Reihenfolge der Dokumente in der Seitenleiste fest. Verwenden Sie dies für Ihre „Inhaltsverzeichnis“-Struktur.

Den Ordner „docs“ leeren​

Der Ordner docs/ enthält eine Kopie der docStatic-Dokumentation – also die Seiten, die Sie gerade lesen. Diese dient als Beispiel und nicht als Inhalt für Ihre Website. Löschen Sie sie daher vor der Veröffentlichung und speichern Sie stattdessen Ihre eigenen Themen in docs/. Wenn Sie ihn belassen, veröffentlicht Ihre Website das docStatic-Handbuch unter Ihrem Namen.

Monorepos​

docStatic ermöglicht die Verwendung eines einzigen Repos, das sowohl den Projektcode als auch die Projektdokumentation enthält. In der Docusaurus-Terminologie wird dieses Konzept als „Monorepo“ bezeichnet.

Weitere Informationen findest du unter Monorepos in der Docusaurus-Dokumentation.

Änderungen in der Vorschau anzeigen​

Um Ihre Änderungen während der Bearbeitung der Dateien in der Vorschau anzuzeigen, können Sie einen lokalen Entwicklungsserver starten, der Ihre Website bereitstellt und die neuesten Änderungen widerspiegelt.

Öffnen Sie ein Terminal oder eine Eingabeaufforderung und geben Sie Folgendes ein:

yarn dev

Standardmäßig öffnet sich ein Browserfenster unter http://localhost:3000.

Erstellen​

docStatic verwendet einen statischen Website-Generator, um die Website in einen Ordner mit statischen Inhalten zu erstellen und sie auf einem Webserver bereitzustellen, wo sie angezeigt werden kann. Um die Website zu erstellen, verwenden Sie:

yarn build-local

Die Inhalte werden im Ordner /build generiert, den Sie auf einen beliebigen Hosting-Dienst für statische Dateien wie GitHub Pages, Netlify oder Vercel kopieren können. Weitere Informationen finden Sie unter Bereitstellung in der Docusaurus-Dokumentation.