ADR-004: VitePress para Documentação

Status: Aceito

Data: 2024-11-02

Decisores: Aron Cardoso

Contexto

O projeto precisava de uma solução para documentação técnica que fosse:

• Fácil de escrever (Markdown)
• Rápida de navegar
• Amigável para desenvolvedores
• Com busca integrada
• Versionável via Git

Forças em jogo:

• Simplicidade: Documentação deve ser fácil de atualizar
• Performance: Carregamento rápido para melhor UX
• Manutenibilidade: Menos infraestrutura é melhor
• Acessibilidade: Boas práticas de a11y

Alternativas Consideradas

Opção 1: Docusaurus

• Prós:
  • Muito popular (Facebook/Meta)
  • Ecossistema maduro de plugins
  • Bom suporte a versioning
  • Comunidade grande
• Contras:
  • React-based (mais pesado)
  • Build mais lento
  • Configuração mais complexa
  • Bundle maior

Opção 2: GitBook

• Prós:
  • Interface muito polida
  • Edição online
  • Colaboração integrada
• Contras:
  • Solução comercial (paga)
  • Vendor lock-in
  • Menos controle sobre hospedagem
  • Custos recorrentes

Opção 3: VitePress (Escolhida)

• Prós:
  • Extremamente rápido (Vite)
  • Vue 3 (leve e moderno)
  • Busca local integrada (sem backend)
  • SSG (Static Site Generation)
  • Markdown-first
  • Zero config básica
  • Open source e gratuito
• Contras:
  • Comunidade menor que Docusaurus
  • Menos plugins disponíveis
  • Ainda em beta (na época da escolha)

Opção 4: MkDocs

• Prós:
  • Python-based
  • Muito simples
  • Material theme excelente
• Contras:
  • Python como dependência
  • Menos moderno que soluções JS
  • Busca requer Algolia ou backend

Decisão

Escolhemos VitePress pelos seguintes motivos:

1. Performance excepcional:

   • Build sub-segundo para documentação pequena/média
   • Hot Module Replacement instantâneo em dev
   • Bundles otimizados por page
   • Lighthouse scores 100/100

2. Developer Experience:

   • npm run docs:dev e pronto
   • Markdown puro sem meta-linguagem
   • Componentes Vue quando necessário
   • TypeScript para config

3. Recursos essenciais incluídos:

   • Busca local (MiniSearch)
   • Dark mode nativo
   • Navegação multi-nível
   • Last updated timestamps
   • Sitemap automático

4. Hospedagem simples:

   • Gera HTML estático
   • Deploy em qualquer CDN/host
   • Nixpacks detecta automaticamente
   • Railway/Vercel/Netlify prontos

Consequências

Positivas

• Velocidade de desenvolvimento: Hot reload instantâneo
• Performance em produção: SSG garante carregamento rápido
• Busca sem backend: MiniSearch funciona 100% no cliente
• Manutenção simplificada: Apenas Markdown + Git
• Zero custo de infraestrutura: Hospedagem estática é barata/grátis
• Acessibilidade: Tema default já segue WCAG

Negativas

• Limitações de busca: Busca local não funciona para sites enormes
• Menos plugins: Ecossistema menor que Docusaurus
• Customização: Requer conhecimento de Vue para deep customization
• API versioning: Não tem suporte built-in (precisa manual)

Neutras

• Framework específico: Ligado ao ecossistema Vue
• Markdown extensions: Usa sintaxe própria para alguns recursos

Notas de Implementação

Configuração Atual

// docs/.vitepress/config.ts
export default defineConfig({
  lang: 'pt-BR',
  title: 'Filament Core Suite',
  cleanUrls: true,
  lastUpdated: true,
  search: { provider: 'local' }
  // ...
})

Scripts NPM

{
  "docs:dev": "vitepress dev docs",
  "docs:build": "vitepress build docs",
  "docs:preview": "vitepress preview docs"
}

Deploy

Via Nixpacks (Railway/plataformas similares):

[phases.build]
cmds = ["npm run docs:build"]

[start]
cmd = "npx vitepress preview docs --host 0.0.0.0 --port ${PORT:-4173}"

Busca Localizada

search: {
  provider: 'local',
  options: {
    locales: {
      root: {
        translations: {
          button: { buttonText: 'Buscar' },
          // ...traduções em português
        }
      }
    }
  }
}

Referências

• VitePress Official Docs
• VitePress Config no GitHub