Jamdesk Documentation logo

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)

CampoTipoObrigatórioDescrição
primarystring (hex)SimCor principal da marca
lightstring (hex)NãoCor de destaque do tema claro
darkstring (hex)NãoCor 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.

CampoTipoDescrição
lightstringFavicon para o modo claro (obrigatório ao usar o formato de objeto)
darkstringFavicon para o modo escuro (opcional; usa light como alternativa)
{ "favicon": "/images/favicon.svg" }
{
  "favicon": {
    "light": "/images/favicon.svg",
    "dark": "/images/favicon-dark.svg"
  }
}

Tipo: object

CampoTipoDescrição
lightstringLogo para o modo claro
darkstringLogo para o modo escuro
hrefstringURL 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" }
  }
}
CampoTipoDescrição
familystringNome da família da fonte. Qualquer Google Font funciona; o build faz o download automaticamente
weightnumberPeso único a carregar (por exemplo, 400). Omita para carregar 400, 500, 600, 700
sourcestringURL 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
  }
}
CampoTipoPadrãoDescrição
default"system" | "light" | "dark""system"Modo inicial para visitantes de primeira viagem
strictbooleanfalseQuando 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
  }
}
CampoTipoPadrãoDescrição
timestampbooleanfalseQuando 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
    }
  }
}
CampoTipoPadrãoDescrição
theme"light" | "dark""light""dark" usa texto claro em um fundo escuro e a imagem logo.dark.
brandColorbooleanfalseAplica colors.primary à barra inferior e ao selo da seção (colors.light em um cartão escuro).
accentBarbooleantruefalse remove a barra na parte inferior do cartão.
siteNamebooleantruefalse 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
  }
}
CampoTipoPadrãoDescrição
autoRedirectbooleanfalseQuando 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.

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
  }
}
CampoTipoPadrãoDescrição
contentstring-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.
typestring"info"O estilo do banner: "info", "warning" ou "danger". Consulte Tipos de banner.
dismissiblebooleanfalseQuando 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".

TipoCorÍcone
"info"A cor de destaque do seu temaNenhum
"warning"ÂmbarAviso
"danger"VermelhoAlerta
{
  "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.

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.

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.

docs.json
{
  "navigation": {
    "tabs": [
      {
        "tab": "API Reference",
        "openapi": { "source": "/openapi/api.yaml", "generate": true }
      }
    ]
  }
}
ChaveTipoDescrição
sourcestringCaminho para a especificação, relativo ao seu docs.json
generatebooleantrue 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.
All supported languages
{
  "api": {
    "examples": {
      "languages": ["curl", "python", "javascript", "go", "ruby", "csharp", "java", "rust", "php"]
    }
  }
}
Custom subset
{
  "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.

ValorComportamento
"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:.

ValorComportamento
"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.

ValorFormato 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"
      }
    }
  }
}

tabsPosition

Tipo: "top" | "left"

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

ValorDescriçã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:

TemaPadrã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.

ValorDescriçã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.

CampoTipoObrigatórioDescrição
namestringSimTexto exibido
hrefstringSimURL (link externo)
iconstringNãoNome do ícone do Font Awesome
{
  "anchors": [
    { "name": "Blog", "href": "https://blog.example.com", "icon": "newspaper" }
  ]
}

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é

Tipo: object

CampoTipoDescrição
linksarrayLinks de navegação
links[].labelstringTexto padrão do botão
links[].labelsobjectSubstituições opcionais por idioma, identificadas pelo código do idioma (por exemplo, fr, es). Usa label como alternativa
links[].iconiconÍcone opcional exibido ao lado do rótulo
links[].hrefstringURL de destino
primaryobjectBotão de CTA principal
primary.labelstringTexto padrão do botão
primary.labelsobjectSubstituiçõ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.

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" }
        ]
      }
    ]
  }
}
CampoTipoDescrição
socialsobjectURLs das plataformas de mídia social
linksarrayConfigurações das colunas de links
links[].headerstringTítulo da coluna
links[].itemsarrayMatriz de objetos { label, href }
copyrightstringLinha 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

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.

CampoTipoPadrãoDescrição
promptstringSearch documentation…Texto de espaço reservado exibido no campo de busca
popularPagesarrayQuick Start, IntroductionLinks 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:

CampoTipoObrigatórioDescrição
titlestringSimRótulo exibido para o link
slugstringSimCaminho da página, sem barra inicial ou extensão .mdx (por exemplo, quickstart ou guides/authentication para o arquivo guides/authentication.mdx)
iconstringNãoNome 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.

CampoTipoPadrãoDescrição
enabledbooleantrueDefina false para remover o painel de chat do seu site
starterQuestionsstring[]gerado automaticamenteAté 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
labelstring"Ask AI" no idioma da páginaSubstitui "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.
iconstringsparklesUm 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.

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.

CampoTipoPadrãoDescrição
enabledbooleantrueDefina false para remover o menu de ações de IA do seu site
optionsarraytodas as integradasLista 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.

CampoTipoDescrição
ignorestring[]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"]
    }
  }
}
CampoTipoDescrição
enabledbooleanModo para todo o site. Quando true, todas as páginas exigem a senha (exceto as marcadas como públicas).
hintstring (máx. 200 caracteres)Dica em texto simples exibida na tela de desbloqueio. HTML não é permitido.
publicstring[]Glob patterns de caminhos que ignoram a senha. Aceita * (um segmento) e ** (recursivo). Uma / isolada é rejeitada.
privatestring[]Caminhos exatos que exigem a senha. Definir esse campo sem enabled ativa o modo de páginas específicas.
allowMembersbooleanPermite 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"]
    }
  }
}
CampoTipoDescrição
enabledbooleanAtiva a autenticação JWT. Todas as páginas exigem uma sessão, exceto as marcadas como públicas.
loginUrlstringObrigató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.
publicstring[]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"]
          }
        ]
      }
    ]
  }
}

O que vem a seguir?

Visão geral da navegação

Estruture a navegação da sua documentação

Menu de ações de IA

Personalize o menu de IA em todas as páginas