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" | "dusk" (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" }
  }
}

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

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

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.

Localização

localization

Tipo: object (opcional)

Controle como os visitantes chegam à versão traduzida da sua documentação.

{
  "localization": {
    "autoRedirect": true
  }
}

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 e na cor de destaque do seu tema. 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
  }
}

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

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.

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

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

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

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

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

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

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.

{
  "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 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 ou desativá-lo.

{
  "chat": {
    "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.

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.

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

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

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?