Ihr erster Workspace

Ein Workspace ist der übergeordnete Container für ein Dokumentationsprojekt. Jeder Workspace wird einem Verzeichnis mit Markdown-Dateien zugeordnet und synchronisiert sich optional mit einem Git-Repository.

Workspace-Konzepte

Workspace erstellen

Über CLI

docplatform init \
  --workspace-name "Engineering Docs" \
  --slug eng-docs

Über Web-Oberfläche

1. Melden Sie sich als Super Admin oder Admin an
2. Öffnen Sie den Workspace-Umschalter (Dropdown oben links)
3. Klicken Sie auf Create Workspace
4. Geben Sie einen Namen und Slug ein
5. Konfigurieren Sie optional ein Git-Remote

Git-Repository verbinden

Bidirektionale Synchronisation hält Ihre Workspace-Dateien und ein Remote-Git-Repository synchron.

Während der Initialisierung

docplatform init \
  --workspace-name "Engineering Docs" \
  --slug eng-docs \
  --git-url [email protected]:your-org/eng-docs.git \
  --branch main

Nach der Erstellung

Aktualisieren Sie die Workspace-Konfiguration unter .docplatform/workspaces/{id}/.docplatform/config.yaml:

git_remote: [email protected]:your-org/eng-docs.git
git_branch: main
git_auto_commit: true
sync_interval: 300  # Sekunden

Starten Sie dann den Server neu oder lösen Sie eine manuelle Synchronisation über die Web-Oberfläche aus.

SSH-Schlüssel einrichten

Für private Repositories verwendet DocPlatform einen dedizierten SSH-Deploy-Key:

# Deploy-Key generieren (ohne Passphrase)
ssh-keygen -t ed25519 -f ~/.ssh/docplatform_deploy_key -N ""

# Öffentlichen Schlüssel zu den Deploy-Keys Ihres Repositories hinzufügen
cat ~/.ssh/docplatform_deploy_key.pub
# → Kopieren Sie dies nach GitHub/GitLab Einstellungen → Deploy Keys (Schreibzugriff aktivieren)

Setzen Sie die Umgebungsvariable:

export GIT_SSH_KEY_PATH=~/.ssh/docplatform_deploy_key

Wie die Synchronisation funktioniert

┌─────────────┐     auto-commit + push      ┌──────────────┐
│ Web Editor   │ ──────────────────────────► │ Remote Repo  │
│ (browser)    │                             │ (GitHub, etc)│
│              │ ◄────────────────────────── │              │
└─────────────┘     polling / webhook        └──────────────┘

Web → Git: Wenn Sie im Editor speichern, schreibt DocPlatform die .md-Datei, erstellt automatisch einen Commit mit einer beschreibenden Nachricht und pusht zum Remote.

Git → Web: DocPlatform pollt das Remote (Standard: alle 5 Minuten) oder lauscht auf Webhooks. Neue Commits werden gepullt und die Web-Oberfläche aktualisiert sich in Echtzeit über WebSocket.

Konflikte: Wenn beide Seiten dieselbe Datei zwischen Synchronisationen ändern, erkennt DocPlatform die Kollision anhand von Content-Hashes, gibt HTTP 409 zurück und stellt beide Versionen zum Download bereit, damit Sie den Konflikt manuell lösen können.

Inhalte organisieren

Seitenhierarchie

Seiten können beliebig tief verschachtelt werden. Die Dateistruktur in docs/ wird direkt auf die URL-Struktur abgebildet:

docs/
├── index.md                → /p/eng-docs/
├── getting-started.md      → /p/eng-docs/getting-started
├── api/
│   ├── index.md            → /p/eng-docs/api/
│   ├── authentication.md   → /p/eng-docs/api/authentication
│   └── endpoints.md        → /p/eng-docs/api/endpoints
└── guides/
    ├── deployment.md       → /p/eng-docs/guides/deployment
    └── contributing.md     → /p/eng-docs/guides/contributing

Frontmatter

Jede Seite beginnt mit YAML-Frontmatter:

---
title: Authentication
description: How to authenticate with the API using JWT tokens.
tags: [api, auth, jwt]
published: true
access:
  roles: []           # Rollennamen, die auf diese Seite zugreifen können
  users: []           # @user_id-Einträge für individuellen Zugriff
---

Das Feld title ist erforderlich. Alle anderen Felder sind optional und haben sinnvolle Standardwerte.

Ihr Team einladen

Über Web-Oberfläche

1. Öffnen Sie Workspace Settings → Members
2. Klicken Sie auf Invite
3. Geben Sie die E-Mail-Adresse der Person ein
4. Wählen Sie eine Rolle (Viewer, Commenter, Editor, Admin)
5. Klicken Sie auf Send Invitation

Wenn SMTP konfiguriert ist, wird die Einladung per E-Mail gesendet. Andernfalls wird ein teilbarer Einladungslink angezeigt.

Rollen

Für detaillierte Berechtigungskonfiguration siehe Rollen & Berechtigungen.

Workspace-Einstellungen

Greifen Sie auf Workspace-Einstellungen über die Web-Oberfläche (Settings-Zahnradsymbol) oder direkt durch Bearbeiten der Konfigurationsdatei zu.

Wichtige Einstellungen:

Für die vollständige Konfigurationsreferenz siehe Workspace-Einstellungen.

Nächste Schritte

Ihr Workspace ist bereit. Hier geht es weiter: