Multi-Projekt-Workspaces

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: