Referencia de docs.json

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

Ruta al archivo de favicon (se recomienda SVG).

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

logo

Tipo: object

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

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

---
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 URL 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 visualización 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 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 "Pruébalo" en cada página openapi: y api: por defecto.

{
  "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 utilizado 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 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 del 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 (título generado automáticamente desde el 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 personalizados.

{
  "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 Matemáticas y LaTeX para detalles de uso.

styling.js

Tipo: string | string[]

Archivo(s) 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 IA integrado. El chat está habilitado por defecto 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 IA para detalles sobre cómo funciona el chat y lo que ven los visitantes.

Menú de acciones IA

contextual

Tipo: object (opcional)

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

Claves de opciones 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 IA 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 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 Resumen del CLI: Corrector ortográfico para detalles de uso y el modo de corrección interactiva.

Imágenes

images.convertToWebp

Tipo: boolean (opcional, predeterminado false)

Habilita la conversión automática a WebP de activos PNG y JPG durante los builds. Los archivos convertidos suelen ser 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 forma 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 almacenamiento en 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 se establece 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 el mismo mensaje de contraseña en el 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, incluido el flujo en el dashboard y cómo interactúan los 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?