Estructura de directorios

Esta página muestra cómo organizar los archivos en un repositorio de documentación de Jamdesk, desde el mínimo de dos archivos hasta una estructura completa de varios directorios.

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 Referencia de docs.json para ver todas las opciones.

Organización de páginas

Estructura 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úyelo 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 ver un ejemplo en producción, consulta Ejemplo de OpenAPI.

Archivos de especificación específicos por idioma

Para sitios de documentación multilingües, agrega 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 → Traducción de 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 commit.

¿Qué sigue?