Referência de docs.json
Referência completa de todos os campos do docs.json: temas, cores, navegação, abas, integração com OpenAPI, marca, SEO, análise e chat de IA.
O arquivo docs.json é a configuração central do seu site de documentação Jamdesk.
As principais configurações do seu docs.json são exibidas no Dashboard em Project Settings → Configuration Highlights. Essa visualização é somente leitura e é atualizada automaticamente após cada build bem-sucedido.
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. Para alterar o formato do título da aba, consulte seo.titleTemplate.
{ "name": "Acme API Docs" }
theme
Tipo: "jam" | "nebula" | "pulsar" | "halo" | "dusk" (obrigatório)
Design limpo e moderno com a fonte Inter. Navegação baseada no cabeçalho.
Ideal para: a maioria dos sites de documentação e referências de API
colors
Tipo: object (obrigatório)
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
primary | string (hex) | Sim | Cor principal da marca |
light | string (hex) | Não | Cor de destaque do tema claro |
dark | string (hex) | Não | Cor de destaque do tema escuro |
{
"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.
| Campo | Tipo | Descrição |
|---|---|---|
light | string | Favicon para o modo claro (obrigatório ao usar o formato de objeto) |
dark | string | Favicon para o modo escuro (opcional; usa light como alternativa) |
{ "favicon": "/images/favicon.svg" }
{
"favicon": {
"light": "/images/favicon.svg",
"dark": "/images/favicon-dark.svg"
}
}
logo
Tipo: object
| Campo | Tipo | Descrição |
|---|---|---|
light | string | Logo para o modo claro |
dark | string | Logo para o modo escuro |
href | string | URL aberta quando o logo é clicado |
{
"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" }
}
}
| Campo | Tipo | Descrição |
|---|---|---|
family | string | Nome da família da fonte. Qualquer Google Font funciona; o build faz o download automaticamente |
weight | number | Peso único a carregar (por exemplo, 400). Omita para carregar 400, 500, 600, 700 |
source | string | URL ou caminho relativo a / para um arquivo de fonte hospedado por você. Ignora o Google Fonts |
format | "woff" | "woff2" | Obrigatório quando source é definido |
Tanto heading quanto body aceitam os mesmos campos. Consulte Tematização → Tipografia para obter orientações sobre a escolha de fontes.
Aparência
appearance
Tipo: object (opcional)
Controle o comportamento padrão do modo escuro do seu site.
{
"appearance": {
"default": "dark",
"strict": true
}
}
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
default | "system" | "light" | "dark" | "system" | Modo inicial para visitantes de primeira viagem |
strict | boolean | false | Quando true, oculta o alternador da barra de navegação para que os visitantes permaneçam em default |
Consulte Tematização → Modo escuro para saber como o alternador se comporta.
Metadados da página
metadata
Tipo: object (opcional)
Controle os metadados da página exibidos em todas as páginas de documentação.
{
"metadata": {
"timestamp": true
}
}
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
timestamp | boolean | false | Quando true, exibe uma linha no estilo "Last updated on June 15, 2026" no rodapé de todas as páginas. A data vem do último commit do Git que alterou a página, portanto permanece automaticamente precisa a cada build. |
A data é renderizada no site publicado e em jamdesk dev. Ela corresponde ao commit mais recente que modificou o arquivo de cada página, portanto as páginas que você não editou mantêm a data original.
SEO
seo.titleTemplate
Tipo: string (opcional)
Padrão: %s — <nome>, em que <nome> é o seu name
Defina o formato do título da página na aba do navegador e nos resultados de busca. Coloque %s onde o título da página deve aparecer. Todo %s é substituído. O modelo pode ter até 200 caracteres. Se não tiver %s, o build falha e o jamdesk validate mostra o erro.
{
"seo": {
"titleTemplate": "%s | Acme"
}
}
Uma página com o título Getting started passa a mostrar Getting started | Acme. Use apenas "%s" para omitir o nome do site. Isso não altera og:title nem twitter:title. Consulte Títulos de página para as páginas sem título.
seo.socialCard
Tipo: object (opcional)
Altere o cartão social que o Jamdesk gera para cada página. Sem essa chave, os cartões mantêm a aparência padrão.
{
"seo": {
"socialCard": {
"theme": "dark",
"brandColor": true
}
}
}
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
theme | "light" | "dark" | "light" | "dark" usa texto claro em um fundo escuro e a imagem logo.dark. |
brandColor | boolean | false | Aplica colors.primary à barra inferior e ao selo da seção (colors.light em um cartão escuro). |
accentBar | boolean | true | false remove a barra na parte inferior do cartão. |
siteName | boolean | true | false oculta o nome do site abaixo do logotipo. O nome permanece quando o cartão exibe seu favicon no lugar do logotipo. |
customImage | "background" | "replace" | "background" | "replace" usa seu og:image como o cartão inteiro, sem nenhum texto sobre ele. |
O cartão só consegue renderizar logotipos SVG, PNG e JPG, e o Jamdesk converte os arquivos de logotipo PNG e JPG para WebP durante o build do site. Use um logotipo SVG para exibir o logotipo completo no cartão. O cartão não consegue renderizar texto dentro de um logotipo SVG, então converta qualquer texto em contornos (paths) na sua ferramenta de design e exporte o SVG novamente.
Consulte Personalizar o cartão social para saber o que cada opção faz e qual imagem uma página usa.
Localização
localization
Tipo: object (opcional)
Controle como os visitantes chegam à versão traduzida da sua documentação.
{
"localization": {
"autoRedirect": true
}
}
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
autoRedirect | boolean | false | Quando true, um visitante que chega pela primeira vez à raiz da sua documentação é enviado para o idioma correspondente ao cabeçalho Accept-Language do navegador dele. Requer duas ou mais entradas em navigation.languages. |
Somente as raízes são redirecionadas. Um link profundo como /guides/authentication sempre serve a página que ele nomeia, portanto um link que você cola em um chamado abre a mesma página para todo mundo. Os rastreadores dos mecanismos de busca nunca são redirecionados, então suas tags hreflang continuam decidindo o que é indexado.
O idioma do visitante fica memorizado por um ano. Escolher um idioma no seletor substitui a correspondência automática daí em diante.
Consulte Suporte multilíngue → Roteamento automático de idioma para conhecer o comportamento completo.
Banner
banner
Exiba uma barra de anúncio em todo o site, fixada no topo de cada página, acima do cabeçalho, em largura total. Use-a para lançamentos, migrações, períodos 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
}
}
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
content | string | - | Obrigatório. O texto do banner. Aceita formatação inline básica: links [text](url), negrito (**text**) e itálico (*text*). Componentes MDX personalizados não são compatíveis. |
type | string | "info" | O estilo do banner: "info", "warning" ou "danger". Consulte Tipos de banner. |
dismissible | boolean | false | Quando true, exibe um botão de fechar. Depois que um visitante dispensa o banner, ele permanece oculto para essa pessoa até que você altere content ou type. Editar a mensagem faz com que ela volte a ser exibida. |
O banner é renderizado no site publicado e em jamdesk dev. Banners por aba não são compatíveis atualmente.
Tipos de banner
Escolha um type de acordo com a urgência da mensagem. Se você não informar, o banner usa "info".
| Tipo | Cor | Ícone |
|---|---|---|
"info" | A cor de destaque do seu tema | Nenhum |
"warning" | Âmbar | Aviso |
"danger" | Vermelho | Alerta |
{
"banner": {
"content": "Scheduled maintenance Saturday 10:00 UTC.",
"type": "warning",
"dismissible": true
}
}
Versões da CLI anteriores à 1.1.231 rejeitam type em jamdesk dev e jamdesk validate. Execute jamdesk update para instalar a versão mais recente.
Para mudar as cores, consulte CSS personalizado → Banner.
Um banner diferente por idioma
Cada entrada de navigation.languages pode ter seu próprio banner, com os mesmos campos. Nas páginas desse idioma, ele substitui o banner de nível superior. Um idioma sem banner próprio mostra o banner de nível superior.
Neste exemplo, as páginas em inglês mostram o banner de nível superior e as páginas em alemão mostram um banner em alemão:
{
"banner": {
"content": "Scheduled maintenance Saturday 10:00 UTC.",
"type": "warning"
},
"navigation": {
"languages": [
{
"language": "en",
"tabs": [...]
},
{
"language": "de",
"banner": {
"content": "Geplante Wartung am Samstag um 10:00 UTC.",
"type": "warning"
},
"tabs": [...]
}
]
}
}
O banner de um idioma não herda campos do banner de nível superior. Defina type e dismissible nele se precisar.
Quando um banner dispensado volta a aparecer
Um visitante que fecha um banner só volta a vê-lo quando você muda o content ou o type.
Se um visitante fechar o banner de nível superior, ele continua oculto em todos os idiomas que o exibem. O banner próprio de um idioma é lembrado separadamente. Fechar o banner em alemão não oculta o banner em inglês.
Em caso de indisponibilidade, use "type": "danger" e não inclua dismissible. Assim os visitantes não conseguem fechar o banner até você removê-lo.
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 configurado, você pode gerar páginas de endpoints adicionando um campo openapi no frontmatter de uma página:
---
title: Create Ticket
openapi: /openapi/api.yaml POST /tickets
---
Se tiver apenas uma especificação listada, você também pode usar o formato curto:
---
title: Create Ticket
openapi: POST /tickets
---
Consulte Exemplo de OpenAPI para ver uma página de endpoint ativa 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), e o Jamdesk o disponibilizará nas URLs desse idioma. Consulte Tradução de especificações OpenAPI.
Uma chave asyncapi é aceita em qualquer lugar onde openapi é aceito, mas o Jamdesk ainda não renderiza especificações AsyncAPI — nada é gerado a partir dela. O jamdesk validate emite um aviso quando encontra uma, para que uma configuração aparentemente compatível não permaneça assim até o build do site.
navigation openapi (páginas geradas)
Tipo: object
Coloque um objeto openapi em 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. Nada para escrever, nada para fazer commit.
{
"navigation": {
"tabs": [
{
"tab": "API Reference",
"openapi": { "source": "/openapi/api.yaml", "generate": true }
}
]
}
}| Chave | Tipo | Descrição |
|---|---|---|
source | string | Caminho para a especificação, relativo ao seu docs.json |
generate | boolean | true cria as páginas e a barra lateral. Sem ele, a chave permanece inativa |
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 alternativa o primeiro segmento significativo do caminho, portanto /api/v1/auctions/{auctionId} fica em Auctions. Os títulos vêm do summary da operação quando a especificação o possui; caso contrário, vêm do método e do caminho — e uma operação que trata de um único recurso recebe um título no singular (GET /users/{id} → "Get User").
generate é opcional por construção. Um "openapi": "/openapi/api.yaml" simples em uma aba, ou um objeto sem generate: true, continua fazendo exatamente o que fazia antes — assim, nenhuma configuração existente ganha cem páginas no próximo build.
Um arquivo .mdx versionado sempre vence uma colisão de slug, portanto você pode adotar a geração gradualmente: ative-a e depois exclua suas páginas de endpoints escritas manualmente, uma por vez, quando estiver pronto.
Se você renomear posteriormente um caminho na especificação, o slug gerado será alterado junto 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, para que links recebidos e favoritos continuem funcionando após a renomeação. Seus próprios redirecionamentos e qualquer página ativa ainda têm precedência.
Limitações atuais. A geração é executada apenas em navigation.tabs de nível superior — não em grupos, âncoras ou abas aninhadas em languages ou versions — e produz páginas somente para o idioma padrão. Uma chave directory é aceita pelo schema, mas não afeta onde as páginas são colocadas.
api.mdx.server
Tipo: string
URL base usada nos exemplos de código em páginas com frontmatter api: (o tipo escrito em MDX, não páginas openapi:, que obtêm seus servidores da especificação).
{
"api": {
"mdx": {
"server": "https://api.example.com"
}
}
}
Uma matriz é aceita por compatibilidade, mas somente a primeira entrada é usada — tudo depois dela é descartado. O jamdesk validate avisa quando você lista mais de uma.
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 em 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
bash é um alias de curl; ambos produzem a mesma saída. Use o rótulo que preferir.{
"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.
| Valor | Comportamento |
|---|---|
"all" | Os exemplos incluem todos os parâmetros com valores de preenchimento |
"required" | Os exemplos incluem somente os parâmetros marcados como required na especificação |
{
"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:.
| Valor | Comportamento |
|---|---|
"interactive" | Playground completo: preencher parâmetros, gerar código e enviar requisições (padrão) |
"simple" | Preencher parâmetros e copiar o código, mas sem botão Send |
"none" | Playground desativado |
{
"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.
| Valor | Formato do cabeçalho |
|---|---|
"bearer" | Authorization: Bearer <token> |
"basic" | Authorization: Basic <base64> |
"key" | Cabeçalho personalizado (consulte api.mdx.auth.name) |
"cobo" | Autenticação específica do Cobo |
{
"api": {
"mdx": {
"auth": {
"method": "bearer"
}
}
}
}
api.mdx.auth.name
Tipo: string
Nome de cabeçalho personalizado 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.
| Valor | Descrição |
|---|---|
"top" | As abas aparecem na barra de abas do cabeçalho |
"left" | As abas aparecem no topo da barra lateral |
O valor padrão depende do seu tema:
| Tema | Padrão |
|---|---|
| jam | "left" |
| nebula | "left" |
| pulsar | "top" |
| halo | "left" |
| dusk | "left" |
{ "tabsPosition": "left" }
tabsAlignment
Tipo: "start" | "center" | "end"
Define o alinhamento horizontal da linha de abas quando as abas ficam no cabeçalho (tabsPosition: "top"). Não tem efeito com tabsPosition: "left" nem no tema Pulsar, que coloca as abas superiores no lado direito do cabeçalho.
| Valor | Descrição |
|---|---|
"start" | As abas ficam à esquerda do cabeçalho (padrão) |
"center" | As abas ficam centralizadas no cabeçalho |
"end" | As abas ficam à direita do cabeçalho |
{ "tabsPosition": "top", "tabsAlignment": "center" }
anchors
Tipo: array
Links externos exibidos no topo da barra lateral em todas as páginas.
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
name | string | Sim | Texto exibido |
href | string | Sim | URL (link externo) |
icon | string | Não | Nome do ícone do Font Awesome |
{
"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 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
| Campo | Tipo | Descrição |
|---|---|---|
links | array | Links de navegação |
links[].label | string | Texto padrão do botão |
links[].labels | object | Substituições opcionais por idioma, identificadas pelo código do idioma (por exemplo, fr, es). Usa label como alternativa |
links[].icon | icon | Ícone opcional exibido ao lado do rótulo |
links[].href | string | URL de destino |
primary | object | Botão de CTA principal |
primary.label | string | Texto padrão do botão |
primary.labels | object | Substituições opcionais por idioma, identificadas pelo código do idioma. Usa label como alternativa |
{
"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"
}
}
}
labels é opcional. Documentações em um único idioma podem omiti-lo. Quando definido, o idioma da URL atual (por exemplo, /fr/...) seleciona a substituição correspondente.
footer
Tipo: object
Configure o rodapé da página com links 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" }
]
}
]
}
}
| Campo | Tipo | Descrição |
|---|---|---|
socials | object | URLs das plataformas de mídia social |
links | array | Configurações das colunas de links |
links[].header | string | Título da coluna |
links[].items | array | Matriz de objetos { label, href } |
copyright | string | Linha de texto simples no fim do rodapé, com até 200 caracteres. Quebras de linha aparecem como espaços. |
Cada entrada de navigation.languages também aceita um footer com os mesmos campos. Ele substitui o rodapé principal naquele idioma, e {} remove os links, os ícones e a linha de copyright. Veja Idiomas.
Plataformas sociais compatíveis: github, x, twitter, linkedin, discord, slack, youtube, instagram, facebook, reddit, telegram, bluesky, threads, medium, hacker-news, website
Estilo
styling.latex
Tipo: boolean
Ative a renderização de fórmulas matemáticas LaTeX com KaTeX. Quando ativada, você pode usar $...$ para fórmulas inline e $$...$$ para equações em bloco.
{
"styling": {
"latex": true
}
}
Consulte Matemática e LaTeX para obter detalhes de uso.
styling.js
Tipo: string | string[]
Arquivo(s) JavaScript personalizado(s) a incluir 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 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 de espaço reservado ou exibir páginas populares no estado vazio.
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
prompt | string | Search documentation… | Texto de espaço reservado exibido no campo de busca |
popularPages | array | Quick Start, Introduction | Links de acesso rápido exibidos antes que o visitante digite uma consulta |
{
"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:
| Campo | Tipo | Obrigatório | Descrição |
|---|---|---|---|
title | string | Sim | Rótulo exibido para o link |
slug | string | Sim | Caminho da página, sem barra inicial ou extensão .mdx (por exemplo, quickstart ou guides/authentication para o arquivo guides/authentication.mdx) |
icon | string | Não | Nome do ícone do Font Awesome exibido ao lado do link (por exemplo, rocket ou bell) |
O campo icon também aceita o objeto completo { "name", "style", "library" }. Consulte Formato de objeto de ícone. Quando popularPages é omitido, o Jamdesk exibe Quick Start e Introduction por padrão.
Chat
chat
Tipo: object (opcional)
Configure o assistente de chat de IA integrado. O chat é ativado por padrão em todos os sites; você só precisa desse campo para personalizar as perguntas iniciais, o nome e o ícone do botão, ou para desativá-lo.
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
enabled | boolean | true | Defina false para remover o painel de chat do seu site |
starterQuestions | string[] | gerado automaticamente | Até 4 perguntas exibidas quando o chat é aberto (5 a 200 caracteres cada). Geradas automaticamente durante os builds quando omitidas. Defina [] para não exibir nenhuma |
label | string | "Ask AI" no idioma da página | Substitui "Ask AI" no botão do chat, no cabeçalho do painel e no atalho de pesquisa. Até 40 caracteres. Vale para todos os idiomas. |
icon | string | sparkles | Um nome de ícone do Font Awesome, a URL de uma imagem ou o caminho de uma imagem no seu projeto. Um ícone do Font Awesome segue a sua cor de destaque; uma imagem é exibida como está, então use uma que fique legível em fundos claros e escuros. |
{
"chat": {
"label": "Acme Assistant",
"icon": "/images/assistant.svg",
"starterQuestions": [
"How do I get started?",
"What API endpoints are available?"
]
}
}
Consulte Chat de 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 é ativado por padrão com todas as opções; você só precisa desse campo para personalizar quais opções aparecem ou desativá-lo.
| Campo | Tipo | Padrão | Descrição |
|---|---|---|---|
enabled | boolean | true | Defina false para remover o menu de ações de IA do seu site |
options | array | todas as integradas | Lista de chaves de opções e/ou objetos de opções personalizados |
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 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 de CLI jamdesk spellcheck. Você só precisa desse campo para adicionar palavras específicas do projeto à lista de ignorados.
| Campo | Tipo | Descrição |
|---|---|---|
ignore | string[] | Palavras a ignorar durante a verificação ortográfica (nomes de produtos, termos técnicos etc.) |
{
"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 conhecer o modo interativo de correção.
Imagens
images.convertToWebp
Tipo: boolean (opcional, padrão false)
Ative a conversão automática de assets PNG e JPG para WebP durante os builds. Os arquivos convertidos normalmente são 60% a 80% menores que os originais, sem perda visível de qualidade. As referências no seu MDX, CSS personalizado, JS 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 modo confiável, e um cartão de prévia 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 funciona o indicador de progresso do build.
Controle de acesso
auth.password
Tipo: object (opcional)
Ative a proteção do site por senha compartilhada. Somente configuração declarativa. Você ainda define a senha real no dashboard depois da execução do próximo build.
Defina auth.password.enabled: true para bloquear todo o site ou liste caminhos em auth.password.private[] para proteger somente determinadas páginas. Ambos acionam o mesmo aviso de senha no dashboard durante o próximo build.
{
"auth": {
"password": {
"enabled": true,
"hint": "Ask your account manager",
"public": ["/marketing/**", "/changelog"]
}
}
}
| Campo | Tipo | Descrição |
|---|---|---|
enabled | boolean | Modo para todo o site. Quando true, todas as páginas exigem a senha (exceto as marcadas como públicas). |
hint | string (máx. 200 caracteres) | Dica em texto simples exibida na tela de desbloqueio. HTML não é permitido. |
public | string[] | Glob patterns de caminhos que ignoram a senha. Aceita * (um segmento) e ** (recursivo). Uma / isolada é rejeitada. |
private | string[] | Caminhos exatos que exigem a senha. Definir esse campo sem enabled ativa o modo de páginas específicas. |
allowMembers | boolean | Permite que o dono do projeto e os membros façam login com a conta Jamdesk em vez da senha. O padrão é false. Sem senha definida, só a equipe consegue entrar. Veja Proteção por senha. |
Consulte Proteção por senha para o passo a passo completo, incluindo o fluxo do dashboard e a interação de public: true / private: true no frontmatter com essas matrizes.
auth.jwt
Tipo: object (opcional)
Coloque todo o site atrás do seu próprio sistema de login. Seu backend assina um token de curta duração para cada usuário conectado, e o Jamdesk o troca por um cookie de sessão. A chave de assinatura é gerada no dashboard, não neste arquivo. auth.jwt e auth.password não podem ser ativados ao mesmo tempo; um build com ambos falha com um config_error.
{
"auth": {
"jwt": {
"enabled": true,
"loginUrl": "https://app.example.com/docs-login",
"public": ["/changelog/**", "/status"]
}
}
}
| Campo | Tipo | Descrição |
|---|---|---|
enabled | boolean | Ativa a autenticação JWT. Todas as páginas exigem uma sessão, exceto as marcadas como públicas. |
loginUrl | string | Obrigatório quando enabled é true. Uma URL absoluta https:// do seu lado. Visitantes sem sessão são enviados para ela com ?redirect=<path>, para que você possa devolvê-los à página solicitada. |
public | string[] | Glob patterns de caminhos que permanecem acessíveis sem login. Usa a mesma sintaxe de auth.password.public e é combinada com public: true no frontmatter e "public": true nos grupos de navegação. |
O acesso por página, adicionalmente, vem de groups no frontmatter da página. Consulte Autenticação JWT para conhecer o formato do token, o fluxo de redirecionamento e o funcionamento dos grupos.
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"]
}
]
}
]
}
}