Workspaces ermöglichen es Ihnen, mehrere unabhängige Dokumentationsprojekte aus einem einzigen Repository zu bauen und zu deployen. Jedes Unterprojekt behält seine eigenen Konfigurationsoptionen und erbt gleichzeitig globale Standards, die im Workspace-Root definiert sind.

docs.example.com/           → Haupt-Produktdokumentation
docs.example.com/sdk/       → SDK-API-Referenz
docs.example.com/cli/       → CLI-Tooling-Leitfaden

Verzeichnis-Einrichtung

Organisieren Sie Ihr Repository in separate Projekt-Unterverzeichnisse. Geteilte statische Assets und globale Workspace-Konfigurationen befinden sich im Repository-Root:

my-docs/
├── assets/                   ← Geteilte statische Assets (von allen Projekten vererbt)
├── main-docs/
│   ├── docmd.config.json     ← Projektkonfiguration (überschreibt Root-Standards)
│   └── docs/                 ← Hauptprojekt Markdown-Inhalte
├── sdk-docs/
│   ├── docmd.config.json     ← SDK-Projektkonfiguration
│   └── docs/                 ← SDK-Projekt Markdown-Inhalte
├── docmd.config.json         ← Workspace-Root-Konfiguration
└── package.json

Workspace-Konfigurationsschema

Die Datei docmd.config.json im Root verwendet den Schlüssel workspace zur Deklaration von Projekten. Top-Level-Parameter (z. B. theme, menubar, logo) dienen als globale Standards für alle Unterprojekte:

{
  "workspace": {
    "projects": [
      { "prefix": "/",    "src": "main-docs", "title": "Docs" },
      { "prefix": "/sdk", "src": "sdk-docs",  "title": "SDK Reference" }
    ],
    "switcher": {
      "enabled": true,
      "position": "sidebar-top"
    }
  },
  "theme": { "name": "default", "appearance": "system" },
  "logo": {
    "light": "assets/logo-dark.svg",
    "dark": "assets/logo-light.svg"
  },
  "menubar": [
    { "text": "GitHub", "url": "https://github.com/docmd-io/docmd", "external": true }
  ]
}

workspace-Optionen

Felder der Projekteinträge

Übersteuerungen auf Projektebene

Unterprojekte können eigene docmd.config.json-Manifeste führen. Auf Projektebene definierte Parameter überschreiben die Standards des Workspace-Roots:

{
  "title": "SDK Reference",
  "src": "docs",
  "plugins": {
    "search": {},
    "openapi": {}
  }
}

Wenn ein Unterprojekt keine lokale Konfigurationsdatei hat, wendet der Compiler automatisches Zero-Config-Routing mit den Workspace-Standards an.

Konfigurations-Kaskadierungshierarchie

Konfigurationsoptionen kaskadieren über ein 3-stufiges Rangfolgemodell:

Das Projekt-Umschaltmenü UI

Der Projekt-Umschalter rendert eine barrierefreie Dropdown-Komponente, die es Lesern ermöglicht, zwischen Workspace-Unterprojekten zu wechseln:

{
  "workspace": {
    "switcher": {
      "enabled": true,
      "position": "sidebar-top"
    }
  }
}

Der Projekt-Umschalter wird automatisch gerendert, wenn zwei oder mehr Workspace-Projekte deklariert sind.

Asset-Verwaltung

• Geteilte Assets: Platzieren Sie Logos, Favicons und globales benutzerdefiniertes CSS im Root-Verzeichnis assets/. Alle Workspace-Projekte erben diese Assets während der Entwicklung und Build-Kompilierung.
• Projekt-Assets: Unterprojekte können lokale assets/-Unterverzeichnisse führen. Projektspezifische Assets überschreiben geteilte Root-Assets bei Dateinamenskonflikten.

Entwicklungs- & Build-Befehle

npx @docmd/core dev

npx @docmd/core build

Workspace-Einschränkungen

1. Root-Projekt-Anforderung: Genau ein Projekt muss prefix: "/" zuweisen.
2. Eindeutige Routenpräfixe: Jedes Projekt muss eine eindeutige URL-Präfix-Zeichenkette verwenden.
3. Root-Level out-Steuerung: Das Ausgabeverzeichnis (out) wird ausschließlich auf Workspace-Root-Ebene konfiguriert; Unterprojekt-Konfigurationen dürfen out nicht angeben.

Konfigurations-Schema-Migration

Um ältere Workspace-Definitionen auf das moderne workspace-Schemaformat zu aktualisieren, führen Sie den automatisierten CLI-Migrationshelfer aus: