Referencia de docs.json

El archivo docs.json es la configuración central de tu sitio de documentación de Jamdesk.

Campos obligatorios

name

Tipo: string (obligatorio)

El nombre de tu sitio de documentación. Se muestra en el encabezado y en la pestaña del navegador. Para cambiar el formato del título de la pestaña, consulta seo.titleTemplate.

{ "name": "Acme API Docs" }

theme

Tipo: "jam" | "nebula" | "pulsar" | "halo" | "dusk" (obligatorio)

colors

Tipo: object (obligatorio)

{
  "colors": {
    "primary": "#635BFF",
    "light": "#7C75FF",
    "dark": "#4F46E5"
  }
}

Marca

favicon

Tipo: string u object

Ruta a tu archivo de favicon (se recomienda SVG). Indica una sola imagen para ambos modos, o variantes light / dark por separado.

{ "favicon": "/images/favicon.svg" }

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

logo

Tipo: object

{
  "logo": {
    "light": "/images/logo-light.webp",
    "dark": "/images/logo-dark.webp",
    "href": "https://yoursite.com"
  }
}

Tipografía

fonts

Tipo: object (opcional)

Sustituye la fuente predeterminada del tema para el texto del cuerpo y los títulos. Cada tema incluye una fuente predeterminada ya ajustada. Define fonts solo cuando necesites un aspecto distinto.

Usa la misma fuente en todas partes:

{
  "fonts": {
    "family": "Lora"
  }
}

Separa títulos y cuerpo:

{
  "fonts": {
    "heading": { "family": "Space Grotesk" },
    "body": { "family": "Inter" }
  }
}

Tanto heading como body aceptan los mismos campos. Consulta Temas → Tipografía para elegir fuentes.

Apariencia

appearance

Tipo: object (opcional)

Controla el comportamiento predeterminado del modo oscuro de tu sitio.

{
  "appearance": {
    "default": "dark",
    "strict": true
  }
}

Consulta Temas → Modo oscuro para ver cómo funciona el interruptor.

Metadatos de página

metadata

Tipo: object (opcional)

Controla los metadatos de página que se muestran en cada página de la documentación.

{
  "metadata": {
    "timestamp": true
  }
}

La fecha se muestra en tu sitio publicado y en jamdesk dev. Refleja el commit más reciente que tocó el archivo de cada página, de modo que las páginas que no has editado conservan su fecha original.

SEO

seo.titleTemplate

Tipo: string (opcional) Valor predeterminado: %s — <nombre>, donde <nombre> es tu name

Define el formato del título de página en la pestaña del navegador y en los resultados de búsqueda. Coloca %s donde debe ir el título de la página. Se reemplazan todos los %s. La plantilla puede tener hasta 200 caracteres. Si no incluye %s, la compilación falla y jamdesk validate muestra el error.

{
  "seo": {
    "titleTemplate": "%s | Acme"
  }
}

Una página con el título Getting started muestra entonces Getting started | Acme. Usa "%s" solo para omitir el nombre del sitio. No cambia og:title ni twitter:title. Consulta Títulos de página para las páginas sin título.

seo.socialCard

Tipo: object (opcional)

Cambia la tarjeta social que Jamdesk genera para cada página. Sin esta clave, las tarjetas mantienen su aspecto predeterminado.

{
  "seo": {
    "socialCard": {
      "theme": "dark",
      "brandColor": true
    }
  }
}

La tarjeta solo puede dibujar logotipos SVG, PNG y JPG, y Jamdesk convierte los archivos de logotipo PNG y JPG a WebP al compilar tu sitio. Usa un logotipo SVG para mostrar tu logotipo completo en la tarjeta. La tarjeta no puede dibujar el texto dentro de un logotipo SVG, así que convierte cualquier texto en contornos (trazados) en tu herramienta de diseño y exporta el SVG de nuevo.

Consulta Personalizar la tarjeta social para saber qué hace cada opción y qué imagen usa una página.

Localización

localization

Tipo: object (opcional)

Controla cómo llegan los visitantes a la versión traducida de tu documentación.

{
  "localization": {
    "autoRedirect": true
  }
}

Solo se redirigen las raíces. Un enlace directo como /guides/authentication siempre sirve la página que nombra, de modo que un enlace que pegues en un ticket abre la misma página para todos. Los rastreadores de los motores de búsqueda nunca son redirigidos, así que tus etiquetas hreflang siguen decidiendo qué se indexa.

El idioma del visitante se recuerda durante un año. Elegir un idioma en el selector de idioma sustituye a partir de entonces la coincidencia automática.

Consulta Idiomas → Enrutamiento automático de idioma para el comportamiento completo.

Banner

banner

Muestra una barra de anuncios para todo el sitio, fijada en la parte superior de cada página, sobre el encabezado, a todo el ancho y con el color de acento de tu tema. Úsala para lanzamientos, migraciones, ventanas de mantenimiento o cualquier mensaje que todos los visitantes deban ver.

{
  "banner": {
    "content": "🎉 Version 2.0 is live! Read the [changelog](/changelog).",
    "dismissible": true
  }
}

El banner se muestra en tu sitio publicado y en jamdesk dev. Se configura de forma global (un solo banner para todo el sitio); por ahora no se admiten banners por pestaña ni por idioma.

OpenAPI

api.openapi

Tipo: string | string[]

Indica los archivos de especificación OpenAPI 3.x que quieres que Jamdesk valide y use para las páginas de endpoint. Usa rutas relativas a tu docs.json.

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

Una vez configurado, puedes generar páginas de endpoint añadiendo un campo openapi en el frontmatter de una página:

---
title: Create Ticket
openapi: /openapi/api.yaml POST /tickets
---

Si solo tienes una especificación en la lista, también puedes usar el formato corto:

---
title: Create Ticket
openapi: POST /tickets
---

Consulta Ejemplo de OpenAPI para ver una página de endpoint real y Estructura de directorios para saber dónde colocar los archivos.

Si tu sitio es multilingüe, coloca un archivo <spec>.<lang>.<ext> junto a cada especificación de origen (p. ej., openapi/api.fr.yaml) y Jamdesk lo sirve en las URL de ese idioma. Consulta Traducir especificaciones de OpenAPI.

navigation openapi (páginas generadas)

Tipo: object

Añade un objeto openapi a una pestaña de navegación y define generate: true, y Jamdesk crea en el build una página de endpoint por cada operación de esa especificación, además de los grupos de la barra lateral que las contienen. No hay nada que redactar ni que confirmar en el repositorio.

{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": { "source": "/openapi/api.yaml", "generate": true }
      }
    ]
  }
}

Las páginas generadas viven bajo el nombre de la propia pestaña, convertido en slug, con un slug construido a partir del método y la ruta: la pestaña anterior coloca POST /tickets en /api-reference/post-tickets. Las operaciones se agrupan por su primer tag; las especificaciones sin tags recurren al primer segmento significativo de la ruta, de modo que /api/v1/auctions/{auctionId} queda bajo Auctions. Los títulos provienen del summary de la operación cuando la especificación lo tiene y, si no, del método y la ruta; y una operación que apunta a un único recurso lleva el título en singular (GET /users/{id} → "Get User").

Un archivo .mdx confirmado en el repositorio siempre gana ante una colisión de slug, por lo que puedes adoptar la generación de forma gradual: actívala y luego elimina tus páginas de endpoint escritas a mano una por una, cuando estés listo.

Si más adelante renombras una ruta en tu especificación, el slug generado se mueve con ella. Jamdesk conserva un historial de slugs por operación y emite en cada build una redirección desde cada URL anterior hasta la actual, de modo que los enlaces entrantes y los marcadores sobreviven al cambio de nombre. Tus propias redirecciones y cualquier página activa siguen teniendo prioridad.

Límites actuales. La generación funciona solo sobre navigation.tabs de nivel superior, no sobre grupos, anchors ni pestañas anidadas bajo languages o versions, y genera páginas únicamente para tu idioma predeterminado. El esquema acepta una clave directory, pero no tiene efecto sobre dónde se colocan las páginas.

api.mdx.server

Tipo: string

URL base usada en los ejemplos de código de las páginas con frontmatter api: (las redactadas en MDX, no las páginas openapi:, que toman sus servidores de la especificación).

{
  "api": {
    "mdx": {
      "server": "https://api.example.com"
    }
  }
}

api.examples.languages

Tipo: string[] Predeterminado: ["curl", "python", "javascript"]

Elige qué lenguajes de programación aparecen en los ejemplos de código de API generados automáticamente en las páginas openapi:. El orden del array determina el orden de las pestañas, y el primer lenguaje queda seleccionado de forma predeterminada.

Valores admitidos: curl, bash, python, javascript, go, ruby, csharp, java, rust, php

{
  "api": {
    "examples": {
      "languages": ["curl", "python", "javascript", "go", "ruby", "csharp", "java", "rust", "php"]
    }
  }
}

{
  "api": {
    "examples": {
      "languages": ["python", "javascript", "go"]
    }
  }
}

api.examples.defaults

Tipo: "required" | "all" Predeterminado: "all"

Controla qué parámetros aparecen en los ejemplos de código generados automáticamente.

{
  "api": {
    "examples": {
      "defaults": "required"
    }
  }
}

api.examples.prefill

Tipo: boolean Predeterminado: false

Si es true, el API Playground rellena previamente los campos de parámetros con los valores example de tu especificación OpenAPI.

{
  "api": {
    "examples": {
      "prefill": true
    }
  }
}

api.playground.display

Tipo: "interactive" | "simple" | "none" Predeterminado: "interactive"

Controla el API Playground en las páginas de endpoint. De forma predeterminada, aparece un botón "Try it" en todas las páginas openapi: y api:.

{
  "api": {
    "playground": {
      "display": "interactive"
    }
  }
}

Consulta API Playground para ver los detalles de uso y las anulaciones por página.

api.mdx.auth.method

Tipo: "bearer" | "basic" | "key" | "cobo"

Método de autenticación usado en los ejemplos de código generados automáticamente. Cuando se define, los ejemplos incluyen el encabezado de autenticación correspondiente.

{
  "api": {
    "mdx": {
      "auth": {
        "method": "bearer"
      }
    }
  }
}

api.mdx.auth.name

Tipo: string

Nombre de encabezado personalizado para la autenticación basada en clave. Solo se usa cuando api.mdx.auth.method es "key".

{
  "api": {
    "mdx": {
      "auth": {
        "method": "key",
        "name": "X-API-Key"
      }
    }
  }
}

Navegación

tabsPosition

Tipo: "top" | "left"

Controla dónde se muestran las pestañas de navegación.

El valor predeterminado depende de tu tema:

{ "tabsPosition": "left" }

tabsAlignment

Tipo: "start" | "center" | "end"

Define la alineación horizontal de la fila de pestañas cuando están en el encabezado (tabsPosition: "top"). No tiene efecto con tabsPosition: "left" ni en el tema Pulsar, que coloca las pestañas superiores en el lado derecho del encabezado.

{ "tabsPosition": "top", "tabsAlignment": "center" }

anchors

Tipo: array

Enlaces externos que aparecen en la parte superior de la barra lateral en todas las páginas.

{
  "anchors": [
    { "name": "Blog", "href": "https://blog.example.com", "icon": "newspaper" }
  ]
}

navigation (estructura)

Tipo: object

La estructura de navegación de tu documentación. Consulta Navegación para ver la documentación detallada.

Las páginas pueden ser cadenas (el título se genera automáticamente a partir del nombre del archivo) u objetos con un título personalizado:

"pages": [
  "introduction",
  { "page": "content/mdx-basics", "title": "MDX Basics" }
]

{
  "navigation": {
    "tabs": [
      {
        "tab": "Docs",
        "icon": "book-open",
        "groups": [
          {
            "group": "Getting Started",
            "pages": ["introduction", "quickstart"]
          }
        ]
      }
    ]
  }
}

Barra de navegación y pie de página

navbar

Tipo: object

{
  "navbar": {
    "links": [
      {
        "label": "Blog",
        "labels": { "fr": "Blog", "es": "Blog" },
        "href": "/blog"
      },
      {
        "label": "Pricing",
        "labels": { "fr": "Tarifs", "es": "Precios" },
        "href": "/pricing"
      }
    ],
    "primary": {
      "type": "button",
      "label": "Dashboard",
      "labels": { "fr": "Tableau de bord", "es": "Panel" },
      "href": "https://app.example.com"
    }
  }
}

footer

Tipo: object

Configura el pie de página con enlaces a redes sociales y columnas de enlaces personalizadas.

{
  "footer": {
    "socials": {
      "github": "https://github.com/yourorg",
      "x": "https://x.com/yourhandle",
      "discord": "https://discord.gg/yourserver"
    },
    "links": [
      {
        "header": "Resources",
        "items": [
          { "label": "Blog", "href": "https://example.com/blog" },
          { "label": "Changelog", "href": "/changelog" }
        ]
      }
    ]
  }
}

Plataformas sociales admitidas: github, x, twitter, linkedin, discord, slack, youtube, instagram, facebook, reddit, telegram, bluesky, threads, medium, hacker-news, website

Estilos

styling.latex

Tipo: boolean

Activa el renderizado de matemáticas con LaTeX mediante KaTeX. Cuando está activado, puedes usar $...$ para matemáticas en línea y $$...$$ para ecuaciones en bloque.

{
  "styling": {
    "latex": true
  }
}

Consulta Matemáticas y LaTeX para ver los detalles de uso.

styling.js

Tipo: string | string[]

Archivos JavaScript personalizados que se incluyen en cada página. Las rutas son relativas a tu directorio de documentación y deben empezar por /.

{
  "styling": {
    "js": "/script.js"
  }
}

Pasa un array para varios archivos:

{
  "styling": {
    "js": ["/chat.js", "/analytics.js"]
  }
}

Sin este campo, Jamdesk detecta automáticamente los archivos .js en la raíz de tu proyecto. Consulta JavaScript personalizado para más detalles.

Búsqueda

search

Tipo: object (opcional)

Personaliza la barra de búsqueda de la documentación. La búsqueda funciona de inmediato; solo necesitas este campo para cambiar el texto de marcador de posición o mostrar páginas populares en el estado vacío.

{
  "search": {
    "prompt": "Ask me anything…",
    "popularPages": [
      { "title": "Quick Start", "slug": "quickstart", "icon": "rocket" },
      { "title": "Authentication", "slug": "guides/authentication", "icon": "key" }
    ]
  }
}

Páginas populares

Cada entrada de popularPages acepta:

El campo icon también acepta el objeto completo { "name", "style", "library" }. Consulta Forma de objeto de icono. Cuando se omite popularPages, Jamdesk muestra Quick Start e Introduction de forma predeterminada.

Chat

chat

Tipo: object (opcional)

Configura el asistente de chat con IA integrado. El chat está activado de forma predeterminada en todos los sitios; solo necesitas este campo para personalizar las preguntas iniciales, el nombre y el icono del botón, o para desactivarlo.

{
  "chat": {
    "label": "Acme Assistant",
    "icon": "/images/assistant.svg",
    "starterQuestions": [
      "How do I get started?",
      "What API endpoints are available?"
    ]
  }
}

Consulta Chat con IA para ver cómo funciona el chat y qué ven los visitantes.

Menú de acciones de IA

contextual

Tipo: object (opcional)

Configura el menú desplegable de acciones de IA que aparece en cada página. Está activado de forma predeterminada con todas las opciones; solo necesitas este campo para personalizar qué opciones aparecen o para desactivarlo.

Claves de opción integradas: copy, view, chatgpt, claude, perplexity, gemini, mcp, cursor, vscode

{
  "contextual": {
    "options": ["copy", "claude", "mcp", "cursor"]
  }
}

Añade opciones personalizadas junto a las integradas:

{
  "contextual": {
    "options": [
      "copy",
      "claude",
      {
        "title": "Ask on Discord",
        "description": "Get help from the community",
        "icon": "discord",
        "href": "https://discord.gg/your-server"
      }
    ]
  }
}

Consulta Menú de acciones de IA para ver la lista completa de opciones y el formato de las opciones personalizadas.

Corrector ortográfico

spellcheck

Tipo: object (opcional)

Configura el comando jamdesk spellcheck de la CLI. Solo necesitas este campo para añadir palabras específicas del proyecto a la lista de ignoradas.

{
  "spellcheck": {
    "ignore": ["Acme", "kubectl", "Terraform"]
  }
}

La CLI incluye más de 180 términos tecnológicos integrados (API, GraphQL, Kubernetes, React, etc.) e ignora automáticamente el nombre de tu proyecto tomado del campo name. Añade solo las palabras específicas de tu proyecto.

Consulta Visión general de la CLI: Spellcheck para ver los detalles de uso y el modo interactivo de corrección.

Imágenes

images.convertToWebp

Tipo: boolean (opcional, valor predeterminado false)

Activa la conversión automática a WebP de los recursos PNG y JPG durante los builds. Los archivos convertidos suelen pesar entre un 60 y un 80 % menos que los originales, sin pérdida visible de calidad. Las referencias en tu MDX, tu CSS personalizado, tu JS personalizado y docs.json se reescriben automáticamente, así que no tienes que cambiar ninguna ruta.

Los favicons, og:image y twitter:image se quedan en su formato original. No todos los rastreadores sociales ni clientes de correo renderizan WebP de forma fiable, y una tarjeta de vista previa rota es peor que un JPG ligeramente más grande.

{
  "images": {
    "convertToWebp": true
  }
}

Consulta Conversión automática de imágenes para saber qué se convierte, cómo funciona la caché y cómo es el indicador de progreso del build.

Control de acceso

auth.password

Tipo: object (opcional)

Activa la protección del sitio con una contraseña compartida. Es solo configuración declarativa. La contraseña en sí la defines en el dashboard después de que se ejecute el siguiente build.

Define auth.password.enabled: true para bloquear todo el sitio, o enumera rutas en auth.password.private[] para proteger solo esas páginas. Ambas opciones activan el mismo aviso de contraseña en el dashboard en el siguiente build.

{
  "auth": {
    "password": {
      "enabled": true,
      "hint": "Ask your account manager",
      "public": ["/marketing/**", "/changelog"]
    }
  }
}

Consulta Protección con contraseña para ver el recorrido completo, incluido el flujo del dashboard y cómo interactúan con estos arrays los valores public: true / private: true del frontmatter.

auth.jwt

Tipo: object (opcional)

Protege todo el sitio con tu propio sistema de inicio de sesión. Tu backend firma un token de corta duración para cada usuario que ha iniciado sesión y Jamdesk lo intercambia por una cookie de sesión. La clave de firma se genera en el dashboard, no en este archivo. auth.jwt y auth.password no pueden estar activados a la vez; un build con ambos activados falla con un config_error.

{
  "auth": {
    "jwt": {
      "enabled": true,
      "loginUrl": "https://app.example.com/docs-login",
      "public": ["/changelog/**", "/status"]
    }
  }
}

El acceso por página, además de esto, proviene de groups en el frontmatter de la página. Consulta Autenticación JWT para ver el formato del token, el flujo de redirección y cómo funcionan los grupos.

Ejemplo completo

{
  "$schema": "https://jamdesk.com/docs.json",
  "name": "Acme Documentation",
  "description": "Learn how to use Acme",
  "theme": "jam",
  "colors": {
    "primary": "#635BFF"
  },
  "favicon": "/images/favicon.svg",
  "logo": {
    "light": "/images/logo-light.webp",
    "dark": "/images/logo-dark.webp"
  },
  "api": {
    "openapi": ["/openapi/api.yaml"],
    "playground": {
      "display": "interactive"
    },
    "examples": {
      "languages": ["curl", "python", "javascript"],
      "prefill": true
    }
  },
  "styling": {
    "latex": true,
    "js": "/script.js"
  },
  "chat": {
    "starterQuestions": ["How do I get started?", "What endpoints are available?"]
  },
  "contextual": {
    "options": ["copy", "claude", "chatgpt", "mcp", "cursor"]
  },
  "spellcheck": {
    "ignore": ["Acme"]
  },
  "anchors": [
    { "name": "Blog", "href": "https://blog.acme.com", "icon": "newspaper" }
  ],
  "navbar": {
    "links": [
      { "label": "Support", "href": "/support" }
    ],
    "primary": {
      "type": "button",
      "label": "Dashboard",
      "href": "https://app.acme.com"
    }
  },
  "navigation": {
    "tabs": [
      {
        "tab": "Docs",
        "icon": "book-open",
        "groups": [
          {
            "group": "Get Started",
            "pages": ["introduction", "quickstart"]
          }
        ]
      },
      {
        "tab": "API Reference",
        "icon": "code",
        "groups": [
          {
            "group": "Endpoints",
            "pages": ["api/users", "api/posts"]
          }
        ]
      }
    ]
  }
}

¿Qué sigue?