Referencia de docs.json

El archivo docs.json es la configuración central de tu sitio de documentación 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.

{ "name": "Acme API Docs" }

theme

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

colors

Tipo: object (obligatorio)

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

Marca

favicon

Tipo: string o object

Ruta al archivo de favicon (se recomienda SVG). Proporciona 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)

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

Usa la misma fuente en todas partes:

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

Fuentes separadas para encabezados y cuerpo:

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

Tanto heading como body aceptan los mismos campos. Consulta Tematización → Tipografía para orientación sobre la elección de fuentes.

Apariencia

appearance

Tipo: object (opcional)

Controla el comportamiento predeterminado del modo oscuro en tu sitio.

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

Consulta Tematización → Modo oscuro para ver cómo se comporta el interruptor.

OpenAPI

api.openapi

Tipo: string | string[]

Lista los archivos de especificación OpenAPI 3.x que deseas 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 listada, también puedes usar el formato corto:

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

Consulta Ejemplo de OpenAPI para ver una página de endpoint en vivo y Estructura de directorios para la ubicación de archivos.

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

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 se selecciona por defecto.

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 endpoint. Aparece un botón "Try it" 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 apropiado.

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

api.mdx.auth.name

Tipo: string

Nombre del 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 (estructura)

Tipo: object

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

Las páginas pueden ser cadenas de texto (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"]
          }
        ]
      }
    ]
  }
}

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 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 matemático LaTeX con 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 detalles de uso.

styling.js

Tipo: string | string[]

Archivos JavaScript personalizados 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 JavaScript personalizado para más detalles.

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 Chat con IA 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 acciones de IA que aparece en cada página. Está 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"]
  }
}

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 la lista completa de opciones y el formato de opciones personalizadas.

Corrección ortográfica

spellcheck

Tipo: object (opcional)

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

{
  "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 del campo name. Solo añade palabras específicas de tu proyecto.

Consulta Descripción general del CLI: Corrección ortográfica para detalles de uso y el modo de corrección interactivo.

Imágenes

images.convertToWebp

Tipo: boolean (opcional, predeterminado false)

Habilita la conversión automática a WebP de los recursos PNG y JPG durante los builds. Los archivos convertidos suelen ser entre un 60-80% más pequeños que los originales sin pérdida de calidad visible. Las referencias en tu MDX, CSS personalizado, JS personalizado y docs.json se reescriben automáticamente, por lo 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 electrónico renderizan WebP de manera fiable, y una tarjeta de preview 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 el caché y el indicador de progreso del build.

Control de acceso

auth.password

Tipo: object (opcional)

Activa la protección con contraseña compartida para tu sitio. Solo configuración declarativa. La frase de contraseña real la estableces en el dashboard después de que se ejecute el próximo build.

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

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

Consulta Protección con contraseña para el recorrido completo, incluyendo el flujo del dashboard y cómo interactúan el frontmatter public: true / private: true 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?