Soporte para Monorepo
Mantén la documentación junto a tu código. Jamdesk admite monorepos y cualquier repositorio donde los docs no estén en la raíz.
Si tu docs.json se encuentra en un subdirectorio -- docs/, packages/docs/ o cualquier otro lugar -- activa el modo monorepo en la configuración del proyecto y especifica la ruta. Jamdesk limitará los builds a ese directorio e ignorará todo lo que esté fuera de él.
Las capturas de pantalla muestran la interfaz en inglés.
Nota: las capturas de pantalla de esta página pueden mostrar la interfaz en inglés.
Requisitos previos: Necesitas un proyecto de Jamdesk conectado a un repositorio de GitHub antes de configurar el soporte para monorepo.
Cómo Jamdesk delimita tu build
Configuración rápida
Ve a tu proyecto en el dashboard de Jamdesk y navega hasta Settings.
En la sección Git Repository, activa la opción Set up as monorepo.
Especifica la ruta al directorio que contiene tu archivo docs.json.
El preview muestra dónde buscará Jamdesk tu archivo de configuración.
Haz clic en Save Changes para aplicar los cambios. El próximo build usará la nueva ruta.
Comprender la ruta de docs
La ruta de docs indica a Jamdesk dónde encontrar tu archivo de configuración docs.json dentro del repositorio.
Introduce solo la ruta del directorio, no el nombre del archivo. Usa docs, no docs/docs.json.
Ejemplos de rutas
| Estructura del repositorio | Valor de la ruta de docs |
|---|---|
my-repo/docs/docs.json | docs |
my-repo/packages/docs/docs.json | packages/docs |
my-repo/apps/website/docs/docs.json | apps/website/docs |
my-repo/documentation/docs.json | documentation |
Qué se incluye
Cuando estableces una ruta de docs, Jamdesk solo procesa los archivos dentro de ese directorio:
- Los archivos de contenido (
.mdx,.md) se compilan en páginas - Los recursos en subdirectorios (como
images/) se incluyen - La configuración (
docs.json) define tu sitio
Los archivos fuera de la ruta de docs se ignoran durante los builds.
Patrones comunes en monorepos
Elige el patrón que se adapte a la estructura de tu proyecto:
Documentación en un directorio de nivel superior.
monorepo/
├── packages/
├── apps/
└── docs/ # Docs path: docs
├── docs.json
├── introduction.mdx
└── guides/
Ruta de docs: docs
Trabajar con recursos
Las rutas de recursos en docs.json son siempre relativas a tu directorio de docs, no a la raíz del repositorio.
Ejemplo
Si tus docs están en packages/docs/:
{
"logo": {
"light": "/images/logo.svg"
},
"favicon": "/images/favicon.svg"
}Estas rutas hacen referencia a:
packages/docs/images/logo.svgpackages/docs/images/favicon.svg
No uses rutas absolutas desde la raíz del repositorio. Esto no funcionará:
"favicon": "/packages/docs/images/favicon.svg"En archivos MDX
La misma regla se aplica a las imágenes en tu contenido:
Esto hace referencia a una imagen en [docs-path]/images/tabs-preview.png.
Enlaces internos
Los enlaces internos funcionan igual independientemente de la estructura de tu repositorio. Usa rutas relativas a la raíz de tus docs:
[See the quickstart guide](/quickstart)
[Installation steps](/quickstart#installation)Estas rutas coinciden con tu estructura de navegación, no con tu sistema de archivos.
Comportamiento del build
Jamdesk solo detecta cambios dentro de tu ruta de docs configurada:
- Los cambios en
packages/docs/**desencadenan un build - Los cambios en
packages/core/**no desencadenan un build
Esto mantiene los builds rápidos y centrados en los cambios de documentación.
¿Necesitas desencadenar un build cuando cambia otro código?
Si generas documentación a partir del código fuente (como docs de API a partir de comentarios en el código), activa una reconstrucción manual desde el dashboard o configura un webhook en tu pipeline de CI.
Compatibilidad con herramientas de workspace
Jamdesk funciona con todas las herramientas principales de monorepo. No se necesita ninguna configuración especial más allá de establecer la ruta de docs.
| Herramienta | Compatible |
|---|---|
| npm workspaces | Sí |
| Yarn workspaces | Sí |
| pnpm workspaces | Sí |
| Turborepo | Sí |
| Nx | Sí |
| Lerna | Sí |
Solución de problemas
- Verifica que la ruta exacta en tu repositorio coincide con lo que introdujiste
- Asegúrate de que
docs.jsonexiste en esa ubicación - Comprueba si hay errores tipográficos: las rutas distinguen entre mayúsculas y minúsculas
- Recuerda: usa
docs, nodocs/docs.json
Verificación rápida: En tu repositorio, el archivo debe existir en [your-docs-path]/docs.json
Las rutas de recursos deben ser relativas a tu directorio de docs.
Correcto - relativo al directorio de docs:
"favicon": "/images/favicon.svg"Incorrecto - absoluto desde la raíz del repositorio:
"favicon": "/packages/docs/images/favicon.svg"Comprueba que tus imágenes existen en [docs-path]/images/.
Solo los cambios dentro de tu ruta de docs configurada desencadenan builds automáticos.
- Verifica que estás modificando archivos dentro de la ruta de docs
- Comprueba que estás haciendo push a la rama correcta
- Consulta el estado de entrega del webhook en la configuración del repositorio de GitHub
Si necesitas que los builds se desencadenen por cambios fuera de la ruta de docs, usa reconstrucciones manuales o webhooks de CI.