Referencia de docs.json

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

Campos requeridos

name

Tipo: string (requerido)

El nombre de tu sitio de documentación. Se muestra en el encabezado y en la pestaña del navegador.

{ "name": "Acme API Docs" }

theme

Tipo: "jam" | "nebula" | "pulsar" (requerido)

colors

Tipo: object (requerido)

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

Branding

favicon

Tipo: string u object

Ruta a tu archivo favicon (se recomienda SVG). Provee una sola imagen para ambos modos, o variantes separadas light / dark.

{ "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)

Sobrescribe la fuente predeterminada del tema para el texto del cuerpo y los encabezados. Cada tema incluye un valor predeterminado ajustado. Configura fonts solo cuando necesites un aspecto diferente.

Usa la misma fuente en todas partes:

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

Separa encabezado y cuerpo:

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

Tanto heading como body aceptan los mismos campos. Consulta Theming → Typography para orientación sobre cómo elegir fuentes.

Apariencia

appearance

Tipo: object (opcional)

Controla el comportamiento predeterminado del modo oscuro de tu sitio.

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

Consulta Theming → Dark Mode para saber cómo se comporta el interruptor.

Metadatos de página

metadata

Tipo: object (opcional)

Controla los metadatos de página que se muestran en cada página de 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, así que las páginas que no has editado conservan su fecha original.

Banner

banner

Muestra una barra de anuncio para todo el sitio, fijada en la parte superior de cada página, encima del encabezado, a ancho completo, en 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 globalmente (un banner para todo el sitio); los banners por tab y por idioma no son compatibles actualmente.

OpenAPI

api.openapi

Tipo: string | string[]

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

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

Una vez configurado, puedes generar páginas de endpoints agregando 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 OpenAPI Example para ver una página de endpoint en vivo y Directory Structure para la ubicación de archivos.

Si tu sitio es multilingüe, coloca un archivo <spec>.<lang>.<ext> junto a cada especificación de origen (por ejemplo, openapi/api.fr.yaml) y Jamdesk lo servirá en las URLs de ese idioma. Consulta Translating OpenAPI Specs.

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 visualización de las pestañas, y el primer lenguaje se selecciona 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

Cuando 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 endpoints. Un botón "Try it" aparece en cada página openapi: y api: de forma predeterminada.

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

Consulta API Playground para detalles de uso y 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 establece, 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 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" }

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 (structure)

Tipo: object

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

Las páginas pueden ser strings (el título se genera automáticamente a partir del nombre de 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"]
          }
        ]
      }
    ]
  }
}

Navbar y footer

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 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

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

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

Consulta Math & LaTeX para detalles de uso.

styling.js

Tipo: string | string[]

Archivo(s) JavaScript personalizado(s) para incluir en cada página. Las rutas son relativas a tu directorio de documentación y deben comenzar con /.

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

Pasa un array para múltiples 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 Custom JavaScript 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 en popularPages acepta:

El campo icon también acepta el objeto completo { "name", "style", "library" }. Consulta Icon object form. 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á habilitado de forma predeterminada en todos los sitios; solo necesitas este campo para personalizar las preguntas iniciales o desactivarlo.

{
  "chat": {
    "starterQuestions": [
      "How do I get started?",
      "What API endpoints are available?"
    ]
  }
}

Consulta AI Chat para detalles sobre cómo funciona el chat y qué ven los visitantes.

Menú de acciones de IA

contextual

Tipo: object (opcional)

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

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

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

Agrega 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 AI Actions Menu para la lista completa de opciones y el formato de opciones personalizadas.

Corrector ortográfico

spellcheck

Tipo: object (opcional)

Configura el comando CLI jamdesk spellcheck. Solo necesitas este campo para agregar palabras específicas del proyecto a la lista de exclusión.

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

El CLI incluye más de 180 términos técnicos integrados (API, GraphQL, Kubernetes, React, etc.) e ignora automáticamente el nombre de tu proyecto a partir del campo name. Agrega solo palabras específicas de tu proyecto.

Consulta CLI Overview: Spellcheck para detalles de uso y modo de corrección interactivo.

Imágenes

images.convertToWebp

Tipo: boolean (opcional, predeterminado false)

Habilita la conversión automática a WebP para los assets PNG y JPG durante los builds. Los archivos convertidos suelen ser 60-80% más pequeños que los originales sin pérdida visible de calidad. Las referencias en tu MDX, CSS personalizado, JS personalizado y docs.json se reescriben automáticamente, así que no necesitas cambiar ninguna ruta.

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

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

Consulta Automatic Image Conversion para saber qué se convierte, cómo funciona el caché y el indicador de progreso del build.

Control de acceso

auth.password

Tipo: object (opcional)

Habilita la protección por contraseña compartida para tu sitio. Solo configuración declarativa. Aún debes establecer la contraseña real en el dashboard después de que se ejecute el próximo build.

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

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

Consulta Password Protection para el recorrido completo, incluyendo el flujo del dashboard y cómo interactúan public: true / private: true del frontmatter con estos arrays.

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?