Estructura de directorios

Una estructura de directorios limpia facilita la navegación, los builds y la colaboración.

Estructura mínima

El proyecto Jamdesk más simple necesita solo dos archivos:

my-docs/
├── docs.json           # Configuration
└── introduction.mdx    # Your first page

Estructura recomendada

Para sitios de documentación más grandes, organiza las páginas en directorios:

my-docs/
├── docs.json
├── introduction.mdx
├── quickstart.mdx
│
├── guides/
│   ├── getting-started.mdx
│   ├── authentication.mdx
│   └── deployment.mdx
│
├── api-reference/
│   ├── overview.mdx
│   ├── endpoints/
│   │   ├── users.mdx
│   │   └── projects.mdx
│   └── webhooks.mdx
│
├── images/
│   ├── logo.svg
│   ├── favicon.svg
│   └── screenshots/
│       └── dashboard.png
│
└── snippets/
    └── api-base-url.mdx

Archivos obligatorios

docs.json

El archivo de configuración que define tu sitio. Debe estar en la raíz de tu directorio de documentación (o en la ruta especificada en la configuración del proyecto).

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "My Documentation",
  "theme": "jam",
  "colors": {
    "primary": "#635BFF"
  },
  "navigation": {
    "groups": [
      {
        "group": "Getting Started",
        "pages": ["introduction", "quickstart"]
      }
    ]
  }
}

Consulta la Referencia de docs.json para ver todas las opciones.

Organización de páginas

Plana vs. anidada

Elige según el tamaño de tu documentación:

docs/
├── docs.json
├── introduction.mdx
├── installation.mdx
├── configuration.mdx
└── troubleshooting.mdx

"pages": ["introduction", "installation"]

Convenciones de nomenclatura

Directorios especiales

images/

Almacena imágenes, logotipos y favicons:

images/
├── logo-light.webp     # Light mode logo
├── logo-dark.webp      # Dark mode logo
├── favicon.svg         # Browser favicon
└── screenshots/        # Documentation screenshots
    └── dashboard.png

Referencia en docs.json:

{
  "logo": {
    "light": "/images/logo-light.webp",
    "dark": "/images/logo-dark.webp"
  },
  "favicon": "/images/favicon.svg"
}

snippets/

Bloques de contenido reutilizables:

snippets/
├── api-base-url.mdx
└── auth-header.mdx

Inclúyelos en las páginas:

<Snippet file="api-base-url.mdx" />

openapi/

Archivos de especificación OpenAPI para la documentación de la API:

openapi/
├── api.yaml
└── webhooks.yaml

Referencia en docs.json:

{
  "api": {
    "openapi": ["/openapi/api.yaml"]
  }
}

Para un ejemplo en producción, consulta el Ejemplo de OpenAPI.

Archivos de especificación por idioma

Para sitios de documentación en varios idiomas, añade archivos de especificación traducidos junto al original con un infijo de código de idioma:

openapi/
├── api.yaml
├── api.fr.yaml
├── api.es.yaml
└── api.zh.yaml

Jamdesk sirve automáticamente la especificación correcta cuando una página se renderiza bajo un prefijo de idioma (/fr/…, /es/…, etc.). Consulta Soporte multilingüe → Traducir especificaciones OpenAPI para conocer las reglas completas sobre qué traducir y qué mantener idéntico.

Archivos a ignorar

Crea un .gitignore para excluir los artefactos de build:

.jamdesk/
node_modules/
.DS_Store
*.log

El directorio .jamdesk/ contiene la caché de desarrollo local y no debe incluirse en el repositorio.

¿Qué sigue?