Na construção de portais de documentação para desenvolvedores modernos, um número expressivo de equipes de engenharia e redação técnica adota o Mintlify. Em vez de lidar com roteamentos complexos em frontend ou folhas de estilo CSS manuais, o Mintlify adota o conceito de "documentação como código" (Docs-as-Code). Toda a identidade visual e a arquitetura da informação são consolidadas em um único arquivo declarativo na raiz do repositório: docs.json (anteriormente mint.json). As equipes podem definir parâmetros de marca, barras laterais com seções retráteis e grupos de abas superiores diretamente em JSON sob controle de versão, junto com seus arquivos MDX.
Este artigo detalha como equipes de documentação técnica configuram a identidade visual corporativa, estruturam barras laterais de navegação e organizam grupos de abas para portais de desenvolvedores de nível corporativo.
1. Arquitetura central de configuração: O esquema docs.json
Todo o comportamento e a navegação de um site Mintlify são controlados pelo arquivo docs.json na raiz do projeto. O esquema moderno unifica temas visuais, topologia de navegação, recursos de console interativo de API e ferramentas de monitoramento em uma estrutura coesa.
Validação de esquema e convenções de caminhos
Para habilitar o preenchimento automático de campos e a validação em tempo real em editores como o VS Code, as equipes devem declarar o esquema oficial no topo do docs.json:
{
"$schema": "https://mintlify.com/docs.json",
"name": "Central de Desenvolvedores Acme",
"theme": "maple"
}
As principais convenções de estrutura de arquivos incluem:
- Caminhos de arquivo sem extensão: Os caminhos de páginas informados nas listas de navegação são relativos à raiz do repositório e não incluem a extensão
.mdxou.md. Por exemplo,"pages": ["getting-started/quickstart"]aponta diretamente para o arquivogetting-started/quickstart.mdx. - Fluxo de trabalho com Git: Alterações na árvore de tópicos, adições de páginas e refinamentos de cores são gerenciados via branches e Pull Requests, facilitando a revisão por pares e o deploy de pré-visualizações.
- Sincronização com o editor web: Membros de equipe que utilizam o editor visual no navegador do Mintlify podem reordenar páginas arrastando e soltando; a plataforma gera commits Git que atualizam o
docs.jsonde forma transparente.
2. Configurando identidade visual e customização de marca
O Mintlify permite alinhar o portal aos manuais de marca da empresa sem a necessidade de criar regras CSS frágeis. As configurações de marca ficam nos campos de nível superior do docs.json.
Temas de layout (Theme)
O Mintlify fornece um conjunto de temas pré-construídos por meio da propriedade theme:
mint: O layout clássico e equilibrado, ideal para ferramentas gerais e projetos de software livre.maple: Uma estética moderna e limpa, muito popular em ferramentas de IA e produtos SaaS.palm: Estrutura com densidade informativa moderada, adequada para fintechs e ecossistemas empresariais complexos.willow: Uma experiência minimalista focada na leitura contínua.- Opções adicionais incluem
linden,almond,aspen,sequoiaeluma.
Cores da marca e adaptação ao modo escuro
O objeto colors define os tons principais da interface, assegurando contraste legível tanto no modo claro quanto no escuro:
"colors": {
"primary": "#2563EB",
"light": "#60A5FA",
"dark": "#1D4ED8"
}
primary: Cor central da marca utilizada em links, estados de seleção ativa e botões no modo claro.light: Tom de destaque aplicado no modo escuro, mantendo boa leitura sobre fundos escuros.dark: Cor empregada em efeitos de foco/hover e ações secundárias em ambos os modos.
Logotipo de modo duplo e Favicon
Para manter a marca nítida em qualquer fundo, recomenda-se disponibilizar arquivos vetoriais SVG específicos para temas claros e escuros, além de definir o destino do clique:
"logo": {
"light": "/images/logo-light.svg",
"dark": "/images/logo-dark.svg",
"href": "https://acme.com"
},
"favicon": "/images/favicon.svg"
Se logo.href for omitido, clicar no logotipo direcionará o leitor para a página inicial da documentação.
Tipografia, bibliotecas de ícones e fundo
- Tipografia: A propriedade
fontspermite indicar fontes do Google Fonts pelo nome da família (como"Inter"ou"Fira Code"), carregadas assincronamente. Também é possível utilizar arquivos.woff2próprios e customizar separadamente títulos (fonts.heading) e texto comum (fonts.body). - Ícones: O Mintlify possui integração com Font Awesome, Lucide e Tabler. Ao configurar
"icons": { "library": "lucide" }, os nós de navegação aceitam diretamente identificadores como"book-open"ou"terminal", além de suportar SVGs inline ou emojis. - Fundo: É possível adicionar textura visual com
"background": { "decoration": "gradient" }ou"grid". - Fixação de modo: Se a organização exigir exclusivamente a interface escura, pode-se definir
"appearance": { "default": "dark", "strict": true }, o que oculta o seletor de modo claro/escuro para o leitor.
3. Construindo a barra lateral: Grupos, aninhamento e páginas raiz
A barra lateral é o principal guia de leitura sequencial do usuário. No Mintlify, sua estrutura completa é declarada dentro do objeto navigation no docs.json.
Grupos simples e identificados por ícones
Um grupo reúne páginas relacionadas em uma seção nomeada na barra lateral. Requer o identificador group e a lista pages:
"navigation": {
"groups": [
{
"group": "Primeiros Passos",
"icon": "rocket",
"pages": [
"quickstart",
"installation",
"authentication"
]
}
]
}
Aninhamento multinível e controle de recolhimento padrão
Conforme o volume de conteúdo cresce, listas lineares tornam a navegação confusa. O Mintlify permite aninhar grupos dentro do array pages de outro grupo.
Para evitar sobrecarga de informações, o estado inicial de abertura pode ser determinado pelo booleano expanded:
{
"group": "Arquitetura Central",
"icon": "cpu",
"pages": [
"architecture/overview",
{
"group": "Armazenamento de Dados",
"icon": "database",
"expanded": false,
"pages": [
"architecture/storage/relational",
"architecture/storage/caching"
]
},
{
"group": "Segurança e Conformidade",
"icon": "shield-check",
"tag": "NEW",
"pages": [
"architecture/security/rbac",
"architecture/security/encryption"
]
}
]
}
Atenção: Os grupos de nível superior aparecem sempre abertos na barra lateral; a propriedade expanded se aplica aos subgrupos aninhados.
Títulos de grupos clicáveis com página raiz (root)
Por padrão, clicar no título de um grupo apenas abre ou fecha seus subitens. No entanto, muitas equipes preferem que o cabeçalho funcione como uma página introdutória de visão geral.
Ao declarar a propriedade root, o título do grupo fica associado a um arquivo MDX:
{
"group": "Referência da API",
"root": "api/overview",
"pages": [
"api/users",
"api/billing",
"api/webhooks"
]
}
Ao clicar em "Referência da API", o portal renderiza imediatamente api/overview.mdx enquanto expande a lista de endpoints vinculados.
Índices automáticos de diretório (directory)
Para não depender da manutenção manual de sumários de páginas, o Mintlify disponibiliza o recurso directory em grupos que possuem root. O sistema insere um índice automático no final do conteúdo da página raiz.
Opções disponíveis:
"card": Exibe as páginas filhas como cartões horizontais clicáveis contendo títulos e resumos."accordion": Organiza o conteúdo em painéis retráteis, recomendado para listas extensas de referência."none": Desativa a injeção do índice (padrão).
O comportamento de directory é herdado hierarquicamente pelas subpastas, permitindo configurar "directory": "card" globalmente e desativá-lo com "directory": "none" em seções técnicas pontuais.
4. Segmentando portais multiproduto com grupos de abas (Tabs)
Quando uma plataforma técnica agrega manuais de desenvolvimento, referências de API, bibliotecas de SDK e notas de versão, concentrar tudo em uma barra lateral contínua prejudica a experiência do leitor. Os grupos de abas superiores introduzem uma divisão horizontal que separa domínios com clareza.
Abas de navegação no nível do site
As abas delimitam grandes divisões de conteúdo. Cada aba possui seu próprio conjunto de rotas e uma barra lateral exclusiva.
Configuração dentro de navigation.tabs:
"navigation": {
"tabs": [
{
"tab": "Tutoriais e Guias",
"icon": "book-open",
"groups": [
{
"group": "Básico",
"pages": ["guides/overview", "guides/quickstart"]
},
{
"group": "Implantação",
"pages": ["guides/docker", "guides/kubernetes"]
}
]
},
{
"tab": "Referência de API",
"icon": "square-terminal",
"groups": [
{
"group": "Endpoints",
"pages": ["api/v1/auth", "api/v1/payments", "api/v1/webhooks"]
}
]
},
{
"tab": "SDKs",
"icon": "code-2",
"groups": [
{
"group": "Bibliotecas Oficiais",
"pages": ["sdks/node", "sdks/python", "sdks/go"]
}
]
},
{
"tab": "Notas de Versão",
"icon": "megaphone",
"href": "https://changelog.acme.com"
}
]
}
Ao transitar entre "Tutoriais e Guias", "Referência de API" e "SDKs":
- A barra lateral se atualiza instantaneamente para refletir apenas os tópicos vinculados à aba ativa.
- A URL no navegador passa a indicar o prefixo da seção correspondente.
- Links para serviços externos (com
href) permanecem harmonizados no cabeçalho.
Menus suspensos dentro de abas (menu)
Se uma aba principal engloba múltiplos produtos independentes, pode-se incluir a propriedade menu para criar seletores suspensos no cabeçalho:
{
"tab": "Soluções",
"icon": "layers",
"menu": [
{
"item": "Plataforma de Pagamentos",
"icon": "credit-card",
"description": "Documentação para cobranças e conciliação bancária.",
"groups": [
{
"group": "Introdução",
"pages": ["payments/intro", "payments/checkout"]
}
]
},
{
"item": "Gestão de Identidade",
"icon": "key-round",
"description": "Configurações de SSO, SAML e OAuth 2.0 corporativo.",
"groups": [
{
"group": "Autenticação",
"pages": ["identity/overview", "identity/saml"]
}
]
}
]
}
Âncoras globais (Anchors) vs. Abas
- Tabs (Abas): Alternam entre grandes divisões de documentação, reconfigurando completamente a barra lateral.
- Global Anchors (Âncoras globais): Declaradas em
navigation.global.anchors, funcionam como atalhos utilitários fixos (ex: "Status da Operação", "Repositório no GitHub" ou "Canal do Discord"), visíveis independentemente da aba ou página em que o leitor estiver.
Diferenciação: Abas no docs.json vs. Componente <Tabs> no MDX
É fundamental não confundir as abas globais de navegação com as abas de conteúdo:
- Abas globais (
docs.json): Gerenciam as rotas e o cabeçalho estrutural do site. - Componente
<Tabs>em arquivos MDX: Elementos de interface interna para alternar blocos de código em diferentes linguagens (como exemplos em cURL, Python ou Node.js). O Mintlify sincroniza automaticamente as abas ativas em uma mesma página quando possuem os mesmos títulos, a menos que se definasync={false}.
5. Exemplo completo pronto para produção
Abaixo está um arquivo docs.json completo e pronto para uso em produção, contemplando identidade corporativa, âncoras globais, múltiplas abas, subgrupos e índices em cartões:
{
"$schema": "https://mintlify.com/docs.json",
"name": "Documentação CloudScale",
"theme": "maple",
"colors": {
"primary": "#059669",
"light": "#34D399",
"dark": "#047857"
},
"logo": {
"light": "/assets/brand/cloudscale-logo-light.svg",
"dark": "/assets/brand/cloudscale-logo-dark.svg",
"href": "https://cloudscale.dev"
},
"favicon": "/assets/brand/favicon.png",
"appearance": {
"default": "system",
"strict": false
},
"fonts": {
"family": "Inter"
},
"icons": {
"library": "lucide"
},
"background": {
"decoration": "gradient"
},
"navigation": {
"global": {
"anchors": [
{
"anchor": "Status do Sistema",
"icon": "activity",
"href": "https://status.cloudscale.dev"
},
{
"anchor": "Comunidade no Slack",
"icon": "messages-square",
"href": "https://cloudscale.dev/slack"
}
]
},
"tabs": [
{
"tab": "Guias de Produto",
"icon": "book-open",
"groups": [
{
"group": "Visão Geral e Setup",
"root": "guides/index",
"directory": "card",
"pages": [
"guides/quickstart",
"guides/architecture",
"guides/cli-tooling"
]
},
{
"group": "Infraestrutura",
"icon": "server",
"pages": [
"guides/compute-clusters",
{
"group": "Rede e DNS",
"expanded": false,
"pages": [
"guides/networking/vpc-peering",
"guides/networking/tls-certificates"
]
}
]
}
]
},
{
"tab": "Referência de API",
"icon": "square-terminal",
"groups": [
{
"group": "Autenticação",
"pages": [
"api/auth/tokens",
"api/auth/service-accounts"
]
},
{
"group": "API de Computação",
"root": "api/compute/overview",
"pages": [
"api/compute/instances",
"api/compute/snapshots"
]
}
]
}
]
}
}
6. Melhores práticas e prevenção de falhas operacionais
Para assegurar uma operação confiável do portal técnico conforme a equipe se expande:
- Validação prévia com Mintlify CLI: Antes de enviar alterações para o repositório principal, execute
npx mintlify devlocalmente. O servidor acusa imediatamente erros de sintaxe no JSON, links quebrados e páginas declaradas que não existem. - Conferência rigorosa dos caminhos de arquivos: Cada item listado em
"pages"deve possuir correspondência física no repositório. Ao renomear um arquivo MDX, certifique-se de atualizar odocs.jsonno mesmo commit. - Aferição de contraste no modo escuro: Ao escolher a cor
primary, verifique com cuidado o valor emlight. Um contraste inadequado em relação ao fundo escuro prejudica a legibilidade e descumpre requisitos de acessibilidade WCAG AA. - Moderação na profundidade de aninhamento: Recomenda-se limitar a hierarquia da barra lateral a dois níveis (grupo principal > subgrupo > página). Níveis mais profundos exigem rolagem horizontal e dificultam a leitura em telas móveis; caso a complexidade aumente, distribua o conteúdo em abas superiores (Tabs) ou seletores do tipo menu.