Los espacios de trabajo le permiten crear y desplegar múltiples proyectos de documentación independientes desde un solo repositorio. Cada subproyecto mantiene sus propias opciones de configuración mientras hereda los valores predeterminados globales definidos en la raíz del espacio de trabajo.

docs.ejemplo.com/           → Documentación principal del producto
docs.ejemplo.com/sdk/       → Referencia de API del SDK
docs.ejemplo.com/cli/       → Guía de herramientas CLI

Configuración de directorios

Organice su repositorio en subdirectorios de proyectos separados. Los recursos estáticos compartidos y las configuraciones globales del espacio de trabajo residen en la raíz del repositorio:

mis-docs/
├── assets/                   ← recursos estáticos compartidos (heredados por todos los proyectos)
├── main-docs/
│   ├── docmd.config.json     ← config. a nivel de proyecto (anula los valores predeterminados raíz)
│   └── docs/                 ← contenido Markdown del proyecto principal
├── sdk-docs/
│   ├── docmd.config.json     ← config. del proyecto SDK
│   └── docs/                 ← contenido Markdown del proyecto SDK
├── docmd.config.json         ← configuración raíz del espacio de trabajo
└── package.json

Esquema de configuración del espacio de trabajo

El archivo docmd.config.json raíz utiliza la clave workspace para declarar proyectos. Los parámetros de nivel superior (por ejemplo, theme, menubar, logo) actúan como valores predeterminados globales en todos los subproyectos:

{
  "workspace": {
    "projects": [
      { "prefix": "/",    "src": "main-docs", "title": "Docs" },
      { "prefix": "/sdk", "src": "sdk-docs",  "title": "Referencia SDK" }
    ],
    "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 }
  ]
}

Opciones de workspace

Campos de entrada de proyectos

Anulaciones a nivel de proyecto

Los subproyectos pueden mantener manifiestos docmd.config.json dedicados. Los parámetros definidos a nivel de proyecto anulan los valores predeterminados de la raíz del espacio de trabajo:

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

Si un subproyecto omite un archivo de configuración local, el compilador aplica el enrutamiento automático de cero configuración utilizando los valores predeterminados del espacio de trabajo.

Jerarquía en cascada de configuración

Las opciones de configuración se aplican en cascada a través de un modelo de precedencia de 3 capas:

El selector de proyectos en la interfaz

El Selector de proyectos renderiza un componente desplegable accesible que permite a los lectores saltar entre los subproyectos del espacio de trabajo:

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

El Selector de proyectos se renderiza automáticamente cuando se declaran dos o más proyectos en el espacio de trabajo.

Gestión de recursos

• Recursos compartidos: Coloque logotipos, favicons y CSS personalizado global en el directorio raíz assets/. Todos los proyectos del espacio de trabajo heredan estos recursos durante el desarrollo y la compilación.
• Recursos del proyecto: Los subproyectos pueden mantener subdirectorios assets/ locales. Los recursos específicos del proyecto anulan los recursos raíz compartidos cuando los nombres de archivo colisionan.

Comandos de desarrollo y compilación

npx @docmd/core dev

npx @docmd/core build

Restricciones del espacio de trabajo

1. Requisito del proyecto raíz: Exactamente un proyecto debe asignar prefix: "/".
2. Prefijos de ruta únicos: Cada proyecto debe utilizar una cadena de prefijo de URL única.
3. Control de out a nivel raíz: El directorio de salida (out) se configura exclusivamente a nivel de la raíz del espacio de trabajo; las configuraciones de subproyectos no deben especificar out.

Migración del esquema de configuración

Para actualizar las definiciones de espacio de trabajo heredadas al formato de esquema workspace moderno, ejecute el asistente de migración automatizado de la CLI: