Mintlify Docs: O Que É e Como Usar

Você está com dificuldades para criar documentações elegantes e fáceis de usar que não pareçam uma tarefa árdua? Diga olá ao Mintlify, a plataforma nativa de IA que torna a criação de documentações incríveis tão fácil quanto escrever um post de blog. Com mais de 28 mil estrelas no GitHub e clientes como a Stripe, o Mintlify oferece recursos interativos, ferramentas de IA e integrações perfeitas para elevar o nível da sua documentação. Neste guia para iniciantes, vou te acompanhar na instalação do Mintlify, na configuração de um domínio personalizado, no aproveitamento da ingestão de IA, na integração de um servidor MCP, na adição de traduções e no uso do OpenAPI para documentação de API. Seja você um desenvolvedor ou um líder de equipe, você estará entregando documentações de nível profissional rapidamente. Pronto para tornar a documentação divertida? Vamos lá!

💡

Antes de começarmos, se você está procurando otimizar o desenvolvimento da sua API, o Apidog oferece uma plataforma completa para projetar, testar e documentar APIs. Com sua interface intuitiva e recursos robustos, é perfeito tanto para iniciantes quanto para desenvolvedores experientes. O melhor de tudo, você pode começar de graça! (apidog)

button

O que é o Mintlify? Seu Superpoder de Documentação

Mintlify é uma plataforma de documentação moderna que ajuda desenvolvedores a criar documentos bonitos, interativos e otimizados para SEO com o mínimo de complicação. Construído para equipes e projetos de código aberto, ele renderiza arquivos Markdown e MDX em páginas responsivas, suporta integração com o GitHub e inclui recursos orientados por IA, como geração de código e traduções. Vantagens principais incluem:

Editor WYSIWYG: Edite documentos em uma interface baseada no navegador.
Componentes Interativos: Adicione abas, trechos de código e playgrounds de API.
Otimização por IA: Melhore a busca e a acessibilidade com a ingestão de IA.
Customizável: Ajuste temas, fontes e navegação através de um arquivo docs.json.

Com um fluxo de trabalho de arrastar e soltar e taxas de conversão de usuários 40% maiores, o Mintlify é perfeito para startups ou projetos públicos. Vamos configurá-lo

Instalando e Configurando o Mintlify

Começar com o Mintlify é muito fácil, e você precisará do Node.js, da CLI do Mintlify e de uma conta GitHub. Veja como começar, com base no guia oficial.

1. Instale os Pré-requisitos:

Node.js: Baixe a versão 16.6 ou superior em https://nodejs.org/. Verifique com node -v.
Conta GitHub: Crie uma conta em github.com se ainda não tiver.
VS Code: Opcional, mas recomendado para edição. Baixe em code.visualstudio.com.

2. Clone o Starter Kit:

No seu terminal, clone o Starter Kit do Mintlify Starter Kit:

git clone https://github.com/mintlify/starter-kit
cd starter-kit

Isso cria um projeto com uma pasta docs contendo arquivos MDX e um arquivo docs.json para configurações.

3. Instale a CLI do Mintlify:

Instale a CLI globalmente:

npm install -g mintlify-cli

Verifique com mintlify-cli --version (ex: mintlify-cli version 3.1.25).

4. Execute a Prévia Local:

Na pasta starter, inicie o servidor de desenvolvimento:

mintlify-cli dev

Isso abre uma prévia em http://127.0.0.1:3000. Se a porta 3000 estiver ocupada, ele tenta a 3001 ou use --port 3333 para personalizar (ex: mintlify-cli dev --port=3333).

5. Edite Sua Documentação:

Abra o projeto no VS Code (code .).
Navegue até docs/introduction.mdx e mude o campo “title” para “Bem-vindo à Minha Documentação!”. Salve, e a prévia será atualizada instantaneamente.
Explore docs.json para ajustar fontes, cores ou habilitar o modo escuro. Por exemplo:

{
  "name": "Minha Documentação",
  "theme": "prism",
  "colors": { "primary": "#3498db" }
}

Verifique https://mintlify.com/docs para configurações globais como ícones ou logotipos.

Configurei isso em menos de 10 minutos e tive um site ao vivo com meus ajustes — super tranquilo!

Configurando um Domínio Personalizado para o Mintlify

Quer que sua documentação esteja em docs.suaempresa.com em vez de um subdomínio mintlify.app? O Mintlify facilita a configuração de domínios personalizados.

1. Acesse as Configurações:

Faça login no seu Painel do Mintlify em mintlify.com.
Vá para Configurações > Domínio Personalizado.

2. Adicione Seu Domínio:

Insira seu domínio (ex: docs.suaempresa.com).
Siga as instruções de DNS para o seu provedor (ex: Namecheap, GoDaddy):
Adicione um registro CNAME: docs → cname.vercel-dns.com.
Para o Cloudflare, habilite a segurança HTTPS “full strict”.
Se estiver usando o Vercel, adicione um registro de verificação TXT (mostrado no painel).

3. Aguarde a Propagação:

As mudanças de DNS levam até 48 horas, mas geralmente se resolvem mais rápido. Verifique seu domínio em um navegador para confirmar.

Configurei um domínio personalizado para um site de teste, e ele estava no ar em poucas horas — vibrações profissionais o tempo todo!

Aproveitando a Ingestão de IA com o Mintlify

A ingestão de IA do Mintlify torna sua documentação mais inteligente e acessível, permitindo que os usuários pesquisem conteúdo através de consultas alimentadas por IA.

1. Habilite a Ingestão de IA:

No Painel do Mintlify, vá para Produtos > AI Chat.
Ative a ingestão de IA. Isso indexa sua documentação para busca por IA sem configuração extra.
O Mintlify gera automaticamente um sitemap /llms.txt para que LLMs indexem seu conteúdo de forma eficiente.

2. Teste a Busca por IA:

Na sua documentação publicada, use a barra de busca ou o AI Chat (se habilitado via docs.json).
Pergunte: “Como me autenticar com a API?” A IA puxa seções relevantes, como sua página de autenticação.

3. Melhore com Correções de IA:

No editor web, a IA sugere correções de sintaxe para erros de MDX (ex: componentes malformados). Habilite isso em Configurações > Editor.

Experimentei a busca por IA em um site de exemplo, e ela encontrou minha documentação de API instantaneamente — muito mais rápido do que navegar manualmente!

Integrando um Servidor MCP com o Mintlify

O Model Context Protocol (MCP) permite que aplicativos de IA interajam com sua documentação ou APIs. O Mintlify gera um servidor MCP para fazer a ponte entre seu conteúdo e LLMs.

1. Instale a CLI do MCP:

Execute:

npm i @mintlify/mcp

No Painel do Mintlify, vá para Produtos > MCP Server para obter seu comando de instalação único.

2. Configure o Servidor MCP:

Encontre sua Chave de Admin Externa e Chave de API de Chat em Configurações > Chaves de API.
Execute o comando da CLI a partir do painel, inserindo as chaves quando solicitado.
Ative o Acesso OpenAPI para incluir endpoints de API (requer uma especificação OpenAPI).

3. Use o Servidor MCP:

A CLI exibe um comando para iniciar seu servidor (ex: npm --prefix ~/.mcp/mintlify start).
Teste com um cliente MCP como o Windsurf, consultando: “Busque na minha documentação por autenticação de API.” O servidor retorna resultados estruturados.

Instalando o Servidor MCP do Mintlify Localmente

Para executar o servidor MCP do Mintlify na sua máquina:

Execute:

npx @mintlify/mcp add mintlify

Pule o prompt do bearer token pressionando Enter.
Selecione seu cliente MCP (ex: Claude Desktop, Windsurf) que está instalado localmente.
O servidor instala e configura para o cliente escolhido.

Exemplo: Usei o Windsurf, e o terminal me deu:

node C:\User\Me.mcp\mintlify\src\index.js

Execute este comando, clique no ícone de ferramentas no seu cliente e verifique se o servidor está disponível.
Alternativamente, no Painel do Mintlify, vá para MCP Server para encontrar um comando para adicionar o servidor ao seu cliente MCP (ex: Apple DB).

Exemplo de Prompt (no Windsurf):

Write a help doc about this feature based on this PRD, in the style and tone of AppleDB docs.

Ou, para formato compatível com Mintlify:

Write this in markdown using Mintlify components like anchors.

Copie a saída do seu cliente mcp (ex: windsurf ou claude desktop), cole no editor web do Mintlify, mude para o modo visual e visualize!

Configurei um servidor MCP, e ele permitiu que meu assistente de IA consultasse minha documentação como um profissional — coisa futurista!

Adicionando Traduções à Documentação do Mintlify

Quer sua documentação em vários idiomas? As traduções alimentadas por IA do Mintlify tornam a localização muito fácil.

1. Habilite as Traduções:

No Painel do Mintlify, vá para Configurações > Traduções.
Adicione um locale (ex: es para espanhol) e selecione uma versão para traduzir.
O Mintlify traduz automaticamente sua documentação, sincronizando atualizações com a versão principal.

2. Personalize as Traduções:

Edite arquivos MDX traduzidos na pasta de locale do seu repositório (ex: docs/es/).
Conteúdo fixo como “Esta página foi útil?” se adapta ao locale automaticamente.

3. Teste a Tradução:

Na sua documentação publicada, mude os locales através do dropdown de versão (configurado em docs.json).

Verifique se os títulos e o conteúdo refletem o idioma de destino (ex: “¡Bienvenidos!” para espanhol).

Adicionei traduções para espanhol, e minha documentação ficou pronta para o mundo em minutos — uma grande vitória para a acessibilidade!

Usando o Mintlify com o VS Code

Documentando código no VS Code? A extensão do Mintlify torna isso muito fácil!

1. Instale a Extensão do Mintlify:

Abra o Marketplace de Extensões do VS Code.
Busque por “Mintlify” e clique em Instalar.

2. Gere a Documentação:

Destaque o código que você deseja documentar.
Clique no ícone do Mintlify na barra lateral e selecione Generate Docs, ou use o atalho Ctrl + ..
O Mintlify escreve a documentação automaticamente.

Exemplo de Código:

test("@e2e wait for api response", async ({ page }) => {
  const sidemenuPage = new SideMenuPage(page);
  await sidemenuPage.interceptApiLink.click();
  const response = await page.waitForResponse((response) =>
    response.url().includes("/comments")
  );
  expect(response.status()).toBe(200);
  await page.getByText("CREATE post").isVisible();
});

Documentação Gerada:

O bloco de código é um caso de teste que verifica se a resposta da API é recebida com sucesso.

Documentei um script de teste, e o Mintlify acertou a descrição — sem esforço!

Explorando os Recursos do Mintlify

O Mintlify está repleto de ferramentas para fazer sua documentação brilhar. Veja como elevar o nível:

Editor Web: Edite documentos no navegador via Painel > Editor. Digite / para componentes como abas ou callouts.
Temas e Estilização: Personalize cores, fontes ou logotipos em docs.json. Experimente temas como prism ou default.
Integração com GitHub: Instale o App do Mintlify no GitHub para implantar mudanças automaticamente. Verifique o painel para configuração.
Analytics: Acompanhe o engajamento do usuário em Painel > Analytics para ver páginas populares ou pontos de abandono.
Componentes: Adicione acordeões, grupos de código ou diagramas Mermaid via MDX. Veja https://mintlify.com/docs para exemplos.

Ajustei meu tema e adicionei abas, fazendo minha documentação parecer um design profissional em menos de uma hora!

Conclusão: Sua Jornada com o Mintlify Começa

Ótimo trabalho — você desbloqueou o poder do Mintlify para criar documentações incríveis e prontas para IA! Desde a instalação da CLI até a configuração de domínios personalizados, ingestão de IA, servidores MCP, traduções e playgrounds OpenAPI, você está pronto para construir documentações que impressionem os usuários. Experimente novos componentes, adicione mais idiomas ou documente suas APIs com o APIdog! Boa documentação!

button