Construindo Sites de Documentação com Docusaurus

Você precisa de um site de documentação para sua biblioteca, framework ou produto SaaS. Você quer que seja estático, rápido e de fácil manutenção sem precisar construir tudo do zero. O Docusaurus v3 resolve isso bem—é um gerador de sites estáticos maduro, baseado em React, que vem com versionamento, integração de busca e suporte a MDX prontos para uso.

Este guia aborda a arquitetura e configuração prática de um site de documentação com Docusaurus, focando em conceitos que permanecem estáveis entre versões menores.

Arquitetura Central de um Site de Documentação Docusaurus

O Docusaurus organiza o conteúdo em três tipos distintos:

Docs ficam no diretório /docs. Estas são suas páginas de documentação principais, renderizadas com navegação lateral automática e suporte a versionamento. Cada arquivo Markdown ou MDX se torna uma página.

Posts de blog vão em /blog. Estes funcionam bem para changelogs, anúncios de lançamento ou tutoriais que são sensíveis ao tempo.

Páginas em /src/pages são componentes React independentes ou arquivos MDX para páginas de destino personalizadas, seções sobre ou qualquer coisa fora da estrutura docs/blog.

A barra lateral e o modelo de versionamento merecem atenção. O Docusaurus gera automaticamente barras laterais a partir da estrutura de pastas, ou você pode defini-las explicitamente em sidebars.js. Quando você cria uma versão, ele tira um snapshot dos seus docs atuais em versioned_docs/, permitindo que os usuários acessem documentação de versões antigas.

Configuração do Docusaurus v3: Primeiros Passos

O scaffolding moderno suporta npm, Yarn, pnpm e Bun. Escolha o que sua equipe usa:

npx create-docusaurus@latest my-docs classic

O preset classic agrupa o plugin de docs, plugin de blog e tema padrão—suficiente para a maioria dos sites de documentação para desenvolvedores. O Docusaurus v3 requer Node.js 20 ou posterior para desenvolvimento local e CI.

Após o scaffolding, a estrutura do seu projeto fica assim:

my-docs/
├── docs/
├── blog/
├── src/
│   ├── components/
│   ├── css/
│   └── pages/
├── static/
├── docusaurus.config.js
└── sidebars.js

O arquivo docusaurus.config.js controla metadados do site, configuração do tema, navbar, rodapé e opções de plugins. Este único arquivo gerencia a maioria das personalizações sem tocar no código React.

Documentação MDX: Escrevendo Conteúdo

O Docusaurus v3 usa MDX v3, que é mais rigoroso que versões anteriores. Isso importa se você está migrando da v2—o MDX v3 impõe sintaxe JSX adequada e não ignora silenciosamente componentes mal formados.

Cada arquivo de doc suporta frontmatter para metadados:

---
id: getting-started
title: Getting Started
sidebar_position: 1
---

# Getting Started

Your content here. You can import React components directly.

Você pode incorporar componentes React, usar diagramas Mermaid e incluir blocos de código interativos. O alias @site aponta para a raiz do seu projeto para imports.

Para diagramas, habilite o plugin Mermaid na sua configuração:

// docusaurus.config.js
module.exports = {
  markdown: {
    mermaid: true,
  },
  themes: ['@docusaurus/theme-mermaid'],
}

Temas e Personalização

O sistema de plugins permite estender funcionalidades sem fazer fork do tema. Plugins comuns lidam com analytics, sitemaps, suporte a PWA e redirecionamentos.

Para personalização visual, sobrescreva variáveis CSS em src/css/custom.css. O tema usa Infima por baixo dos panos, então você está ajustando tokens de design em vez de escrever estilos de componentes:

:root {
  --ifm-color-primary: #2e8555;
  --ifm-code-font-size: 95%;
}

Personalização mais profunda usa “swizzling”—ejetando componentes do tema para modificá-los. Execute npx docusaurus swizzle para ver os componentes disponíveis. Faça swizzle apenas do que você precisa, pois componentes ejetados requerem atualizações manuais ao atualizar o Docusaurus.

Integração de Busca

A maioria dos sites Docusaurus em produção usa Algolia DocSearch. Candidate-se ao programa gratuito se seus docs são públicos, ou hospede o crawler você mesmo para documentação privada.

A configuração fica em themeConfig:

// docusaurus.config.js
module.exports = {
  themeConfig: {
    algolia: {
      appId: 'YOUR_APP_ID',
      apiKey: 'YOUR_SEARCH_API_KEY',
      indexName: 'YOUR_INDEX_NAME',
    },
  },
}

O DocSearch v4 também suporta Algolia AskAI, que adiciona busca conversacional opcional além da experiência de busca padrão e é configurado como parte da mesma integração Algolia.

Deploy

O Docusaurus compila para HTML, CSS e JavaScript estáticos no diretório /build. Qualquer hospedagem estática funciona: Vercel, Netlify, GitHub Pages, Cloudflare Pages ou sua própria CDN.

npm run build

A saída é um site estático padrão sem necessidade de runtime de servidor. Configure seu provedor de hospedagem para lidar com roteamento client-side servindo index.html para caminhos desconhecidos.

O Que Saber para Produção

Algumas notas práticas para manter um site de documentação para desenvolvedores:

• Versionamento adiciona complexidade. Versione apenas quando os usuários realmente precisarem acessar docs antigos. Muitos projetos funcionam bem com uma única versão “atual”.
• O rigor do MDX captura bugs reais. Se a migração da v2 quebrar páginas, os erros geralmente apontam para problemas reais de JSX que vale a pena corrigir.
• Tempos de build escalam com o conteúdo. Sites grandes se beneficiam de builds incrementais em CI e cache de node_modules.

Conclusão

O Docusaurus cuida da infraestrutura para que você possa focar em escrever boa documentação. A base em React significa que equipes de frontend podem personalizar profundamente quando necessário, enquanto os padrões funcionam bem o suficiente para que muitos sites sejam lançados sem tocar em código React. Comece com o preset clássico, adicione plugins conforme os requisitos surgirem e resista à tentação de personalizar demais antes que o conteúdo da sua documentação esteja sólido.

Perguntas Frequentes

Gain Debugging Superpowers

Unleash the power of session replay to reproduce bugs, track slowdowns and uncover frustrations in your app. Get complete visibility into your frontend with OpenReplay — the most advanced open-source session replay tool for developers. Check our GitHub repo and join the thousands of developers in our community.