工作区允许你从单个仓库构建并部署多个独立的文档项目。每个子项目维护其自己的配置选项，同时继承工作区根目录定义的全局默认值。

docs.example.com/           → 主产品文档
docs.example.com/sdk/       → SDK API 参考
docs.example.com/cli/       → CLI 工具指南

目录搭建

将你的仓库组织为单独的项目子目录。共享的静态资源和全局工作区配置保存在仓库根目录：

my-docs/
├── assets/                   ← 共享静态资源（被所有项目继承）
├── main-docs/
│   ├── docmd.config.json     ← 项目级配置（覆盖根默认值）
│   └── docs/                 ← 主项目 Markdown 内容
├── sdk-docs/
│   ├── docmd.config.json     ← SDK 项目配置
│   └── docs/                 ← SDK 项目 Markdown 内容
├── docmd.config.json         ← 工作区根配置
└── package.json

工作区配置架构

根 docmd.config.json 文件使用 workspace 键声明项目。顶层参数（如 theme、menubar、logo）作为所有子项目的 全局默认值：

{
  "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 选项

项目条目字段

项目级覆盖

子项目可以维护专用的 docmd.config.json 清单。在项目级定义的参数将 覆盖 工作区根默认值：

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

如果子项目省略了本地配置文件，编译器会使用工作区默认值应用零配置自动路由。

配置层叠层级

配置选项通过 3 层优先级模型层叠生效：

项目切换器 UI

项目切换器会渲染一个无障碍下拉组件，允许读者在工作区子项目之间切换：

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

当声明了两个或更多工作区项目时，项目切换器会自动渲染。

资源管理

• 共享资源: 将 Logo、Favicon 和全局自定义 CSS 放在根 assets/ 目录中。所有工作区项目在开发和构建编译期间均继承这些资源。
• 项目资源: 子项目可以维护本地 assets/ 子目录。发生文件名冲突时，项目特定的资源会覆盖共享根资源。

开发与构建命令

npx @docmd/core dev

npx @docmd/core build

工作区约束

1. 根项目要求: 必须且仅有一个项目分配 prefix: "/"。
2. 唯一路由前缀: 每个项目必须使用唯一的 URL 前缀字符串。
3. 根级 out 控制: 输出目录 (out) 仅在工作区根级配置；子项目配置不得指定 out。

配置架构迁移

要将旧工作区定义升级到现代 workspace 架构格式，请执行自动化 CLI 迁移助手：