Referência de docs.json

O arquivo docs.json é a configuração central do seu site de documentação Jamdesk.

Campos obrigatórios

name

Tipo: string (obrigatório)

O nome do seu site de documentação. Exibido no cabeçalho e na aba do navegador.

{ "name": "Acme API Docs" }

theme

Tipo: "jam" | "nebula" | "pulsar" | "halo" (obrigatório)

colors

Tipo: object (obrigatório)

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

Marca

favicon

Tipo: string ou object

Caminho para o arquivo do favicon (SVG recomendado). Forneça uma única imagem para os dois modos ou 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"
  }
}

Tipografia

fonts

Tipo: object (opcional)

Substitua a fonte padrão do tema para o texto do corpo e os títulos. Cada tema inclui uma fonte padrão ajustada. Defina fonts somente quando precisar de uma aparência diferente.

Use a mesma fonte em todos os elementos:

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

Separe títulos e corpo:

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

heading e body aceitam os mesmos campos. Consulte Tematização → Tipografia para obter orientações sobre como escolher fontes.

Aparência

appearance

Tipo: object (opcional)

Controle o comportamento padrão do modo escuro do seu site.

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

Consulte Tematização → Modo escuro para saber como o controle funciona.

Metadados da página

metadata

Tipo: object (opcional)

Controle os metadados exibidos em todas as páginas de documentação.

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

A data é exibida no site publicado e em jamdesk dev. Ela representa o commit mais recente que alterou o arquivo de cada página; portanto, as páginas que você não editou mantêm a data original.

Banner

banner

Exiba uma barra de anúncio para todo o site, fixada no topo de cada página, acima do cabeçalho, em largura total e na cor de destaque do seu tema. Use-a para lançamentos, migrações, janelas de manutenção ou qualquer mensagem que todos os visitantes devam ver.

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

O banner é exibido no site publicado e em jamdesk dev. Ele é configurado globalmente (um banner para todo o site); banners por aba e por idioma ainda não são compatíveis.

OpenAPI

api.openapi

Tipo: string | string[]

Liste os arquivos de especificação OpenAPI 3.x que você quer que o Jamdesk valide e use nas páginas de endpoints. Use caminhos relativos ao seu docs.json.

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

Depois de configurar, você pode gerar páginas de endpoints adicionando um campo openapi ao frontmatter de uma página:

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

Se você tiver apenas uma especificação listada, também poderá usar o formato curto:

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

Consulte Exemplo de OpenAPI para ver uma página de endpoint funcional e Estrutura de diretórios para saber onde colocar os arquivos.

Se o seu site for multilíngue, coloque um arquivo <spec>.<lang>.<ext> ao lado de cada especificação de origem (por exemplo, openapi/api.fr.yaml); o Jamdesk o disponibilizará nas URLs desse idioma. Consulte Traduzindo especificações OpenAPI.

navigation openapi (páginas geradas)

Tipo: object

Adicione um objeto openapi a uma aba de navegação e defina generate: true; o Jamdesk criará uma página de endpoint para cada operação dessa especificação no momento do build, além dos grupos da barra lateral que as conterão. Não é necessário escrever nem fazer commit de nada.

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

As páginas geradas ficam sob o próprio nome da aba, convertido em slug, com um slug criado a partir do método e do caminho — a aba acima coloca POST /tickets em /api-reference/post-tickets. As operações são agrupadas pela primeira tag; especificações sem tags usam como fallback o primeiro segmento significativo do caminho. Assim, /api/v1/auctions/{auctionId} fica em Auctions. Os títulos vêm do summary da operação quando a especificação tem esse campo; caso contrário, vêm do método e do caminho. Uma operação que aborda um único recurso recebe um título no singular (GET /users/{id} → "Get User").

Um arquivo .mdx versionado sempre vence uma colisão de slug, para que você possa adotar a geração gradualmente: ative-a e depois exclua, uma a uma, as páginas de endpoint escritas manualmente quando estiver pronto.

Se você renomear posteriormente um caminho na sua especificação, o slug gerado será alterado com ele. O Jamdesk mantém um histórico de slugs por operação e emite um redirecionamento de cada URL anterior para a atual em cada build, preservando links recebidos e favoritos. Seus próprios redirecionamentos e qualquer página ativa ainda têm prioridade.

Limitações atuais. A geração é executada somente em navigation.tabs de nível superior — não em grupos, âncoras ou abas aninhadas em languages ou versions — e produz páginas apenas para o idioma padrão. Uma chave directory é aceita pelo schema, mas não afeta o local onde as páginas são criadas.

api.mdx.server

Tipo: string

URL base usada nos exemplos de código das páginas com frontmatter api: (o tipo criado com MDX, não as páginas openapi:, que obtêm seus servidores da especificação).

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

api.examples.languages

Tipo: string[] Padrão: ["curl", "python", "javascript"]

Escolha quais linguagens de programação aparecem nos exemplos de código de API gerados automaticamente nas páginas openapi:. A ordem da matriz determina a ordem de exibição das abas, e a primeira linguagem é selecionada por padrão.

Valores compatíveis: 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" Padrão: "all"

Controle quais parâmetros aparecem nos exemplos de código gerados automaticamente.

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

api.examples.prefill

Tipo: boolean Padrão: false

Quando true, o API Playground preenche previamente os campos de parâmetros com valores example da sua especificação OpenAPI.

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

api.playground.display

Tipo: "interactive" | "simple" | "none" Padrão: "interactive"

Controla o API Playground nas páginas de endpoints. Um botão "Try it" aparece por padrão em todas as páginas openapi: e api:.

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

Consulte API Playground para obter detalhes de uso e substituições por página.

api.mdx.auth.method

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

Método de autenticação usado nos exemplos de código gerados automaticamente. Quando definido, os exemplos incluem o cabeçalho de autenticação apropriado.

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

api.mdx.auth.name

Tipo: string

Nome personalizado do cabeçalho para autenticação baseada em chave. Usado somente quando api.mdx.auth.method é "key".

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

Navegação

tabsPosition

Tipo: "top" | "left"

Controla onde as abas de navegação são exibidas.

O valor padrão depende do seu tema:

{ "tabsPosition": "left" }

anchors

Tipo: array

Links externos exibidos no topo da barra lateral em todas as páginas.

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

navigation (estrutura)

Tipo: object

A estrutura de navegação da sua documentação. Consulte Navegação para obter a documentação detalhada.

As páginas podem ser strings (com título gerado automaticamente a partir do nome do arquivo) ou objetos com um 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 navegação e rodapé

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

Configure o rodapé da página com links de redes sociais e colunas de links 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 sociais compatíveis: github, x, twitter, linkedin, discord, slack, youtube, instagram, facebook, reddit, telegram, bluesky, threads, medium, hacker-news, website

Estilos

styling.latex

Tipo: boolean

Ative a renderização de fórmulas LaTeX com KaTeX. Quando ativada, você pode usar $...$ para fórmulas inline e $$...$$ para equações em bloco.

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

Consulte Math & LaTeX para obter detalhes de uso.

styling.js

Tipo: string | string[]

Arquivo(s) JavaScript personalizado(s) incluído(s) em todas as páginas. Os caminhos são relativos ao diretório da documentação e devem começar com /.

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

Passe uma matriz para incluir vários arquivos:

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

Sem esse campo, o Jamdesk detecta automaticamente arquivos .js na raiz do projeto. Consulte JavaScript personalizado para obter detalhes.

Busca

search

Tipo: object (opcional)

Personalize a barra de busca da documentação. A busca funciona imediatamente; você só precisa desse campo para alterar o texto do placeholder ou exibir páginas populares no estado vazio.

{
  "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 em popularPages aceita:

O campo icon também aceita o objeto completo { "name", "style", "library" }. Consulte Formato de objeto do ícone. Quando popularPages é omitido, o Jamdesk exibe Quick Start e Introduction por padrão.

Chat

chat

Tipo: object (opcional)

Configure o assistente de chat com IA integrado. O chat vem ativado por padrão em todos os sites; você só precisa desse campo para personalizar as perguntas iniciais ou desativá-lo.

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

Consulte Chat com IA para saber como o chat funciona e o que os visitantes veem.

Menu de ações de IA

contextual

Tipo: object (opcional)

Configure o menu suspenso de ações de IA exibido em todas as páginas. Ele vem ativado por padrão com todas as opções; você só precisa desse campo para personalizar as opções exibidas ou desativá-lo.

Chaves de opções integradas: copy, view, chatgpt, claude, perplexity, gemini, mcp, cursor, vscode

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

Adicione opções personalizadas junto às opções integradas:

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

Consulte Menu de ações de IA para ver a lista completa de opções e o formato das opções personalizadas.

Verificação ortográfica

spellcheck

Tipo: object (opcional)

Configure o comando CLI jamdesk spellcheck. Você só precisa desse campo para adicionar palavras específicas do projeto à lista de ignorados.

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

A CLI inclui mais de 180 termos técnicos integrados (API, GraphQL, Kubernetes, React etc.) e ignora automaticamente o nome do projeto do campo name. Adicione somente palavras específicas do seu projeto.

Consulte Visão geral da CLI: verificação ortográfica para obter detalhes de uso e saber mais sobre o modo interativo de correção.

Imagens

images.convertToWebp

Tipo: boolean (opcional, padrão false)

Ative a conversão automática de assets WebP para PNG e JPG durante os builds. Os arquivos convertidos geralmente são 60–80% menores que os originais, sem perda visível de qualidade. As referências no seu MDX, CSS personalizado, JavaScript personalizado e docs.json são reescritas automaticamente; portanto, você não precisa alterar nenhum caminho.

Favicons, og:image e twitter:image permanecem no formato original. Nem todo crawler de redes sociais ou cliente de e-mail renderiza WebP de forma confiável, e um cartão de pré-visualização quebrado é pior que um JPG um pouco maior.

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

Consulte Conversão automática de imagens para saber o que é convertido, como o cache funciona e como interpretar o indicador de progresso do build.

Controle de acesso

auth.password

Tipo: object (opcional)

Ative a proteção do site por senha compartilhada. A configuração é somente declarativa. Você ainda precisa definir a frase secreta real no dashboard depois da execução do próximo build.

Defina auth.password.enabled: true para bloquear o site inteiro ou liste caminhos em auth.password.private[] para proteger somente determinadas páginas. Ambos acionam a mesma solicitação de senha no dashboard durante o próximo build.

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

Consulte Proteção por senha para ver o passo a passo completo, incluindo o fluxo do dashboard e como public: true / private: true no frontmatter interagem com essas matrizes.

Exemplo 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"]
          }
        ]
      }
    ]
  }
}

O que vem a seguir?