Skip to main content

Introdução

Documentação técnica dos projetos da Caveo, construída com Docusaurus e suporte multilíngue (Português-BR e Inglês).

Sobre o Projeto​

Este é um site de documentação estático baseado em React que agrega e serve documentação de repositórios externos através de uma interface moderna e responsiva. O projeto utiliza Docusaurus como framework principal e suporta conteúdo em português brasileiro (idioma primário) e inglês (idioma secundário).

Tecnologias Principais​

  • Docusaurus: Framework para sites de documentação
  • React: Biblioteca para construção da interface
  • TypeScript: Superset tipado do JavaScript
  • Node.js: Ambiente de execução para scripts
  • Docker: Containerização para desenvolvimento e produção
  • Nginx: Servidor web para ambiente de produção

Estrutura do Projeto​

caveo-docs/
├── docs/                    # Conteúdo da documentação
├── blog/                    # Posts do blog
├── src/
│   ├── components/          # Componentes React reutilizáveis
│   ├── css/                 # Estilos globais
│   └── pages/               # Páginas customizadas
├── static/                  # Recursos estáticos (imagens, fontes)
├── scripts/                 # Scripts utilitários
├── i18n/                    # Traduções (inglês)
├── docusaurus.config.ts     # Configuração principal
└── docker-compose.yml       # Configuração Docker

Funcionalidades​

  • Suporte multilíngue (pt-BR e en)
  • Importação automática de documentação de repositórios externos
  • Interface responsiva e acessível
  • Busca integrada
  • Versionamento de documentação
  • Blog integrado
  • Tema claro/escuro
  • Ambiente Docker para desenvolvimento e produção

Início Rápido​

Instalação Simplificada com Make: Se preferir uma abordagem mais rápida, você pode utilizar o Makefile incluído no projeto. Basta ter o make instalado em seu sistema e executar make start. O comando irá automaticamente instalar as dependências, buscar a documentação externa e iniciar o servidor de desenvolvimento, eliminando a necessidade de gerenciar manualmente cada etapa do processo.

Pré-requisitos​

  • node (versão 20+)
  • npm ou yarn
  • docker e docker compose (opcional)
  • make (opcional)

Instalação​

# Clonar o repositório
git clone <repository-url>
cd caveo-docs

# Instalar dependências
npm install

# Copiar documentação de outros repositórios locais
npm run copy-docs

# Iniciar servidor de desenvolvimento
npm start

Docker​

Desenvolvimento​

docker compose -f docker-compose.dev.yml up

Produção​

docker compose up

Scripts Disponíveis​

npm​

  • npm start - Inicia servidor de desenvolvimento
  • npm run build - Gera build de produção
  • npm run serve - Serve build localmente
  • npm run copy-docs - Copia documentação de outros repositórios locais
  • npm run typecheck - Verifica tipos TypeScript
  • npm run clear - Limpa cache do Docusaurus

make​

  • make check-deps - Verifica se Node.js e npm estão instalados
  • make install-deps - Instala Node.js e npm
  • make install - Instala dependências do projeto
  • make env - Cria arquivo .env com variáveis de ambiente
  • make check-install - Valida instalação e configuração do projeto
  • make start - Instala dependências, busca documentação e inicia servidor de desenvolvimento
  • make build - Gera build de produção
  • make serve - Serve build de produção localmente
  • make typecheck - Verifica tipos TypeScript
  • make clean-cache - Limpa cache do Docusaurus
  • make clean - Deleta arquivos e diretórios não salvos remotamente / listados em .gitignore

Convenções de Código​

Nomenclatura​

  • Componentes: PascalCase (HomepageFeatures)
  • Arquivos: Match com nome do componente (HomepageFeatures.tsx)
  • Variáveis/Funções: camelCase (fetchDocs)
  • Constantes: ALL_CAPS (DOCS_FOLDER)
  • Classes CSS: camelCase (heroBanner)

Commits​

Seguimos Conventional Commits:

  • feat: novas funcionalidades
  • fix: correções de bugs
  • docs: alterações em documentação
  • style: formatação de código
  • refactor: refatoração de código
  • chore: tarefas de manutenção

Branches​

  • feature/descricao-curta - novas funcionalidades
  • fix/descricao-curta - correções
  • docs/descricao-curta - documentação

Conteúdo Multilíngue​

Português-BR (Primário)​

  • Todos os arquivos .md principais devem estar em português brasileiro
  • Usar padrões ABNT para documentação técnica
  • Termos técnicos comuns podem permanecer em inglês (commit, deploy, build)

Inglês (Secundário)​

  • Adicionar traduções com sufixo .en.md quando necessário
  • Manter estrutura paralela em i18n/en/
  • Arquivos em .github/ permanecem apenas em inglês

Contribuindo​

  1. Crie uma branch a partir de main
  2. Faça suas alterações seguindo as convenções
  3. Atualize primeiro o conteúdo em português, depois traduções
  4. Execute npm run build para validar
  5. Crie um Pull Request com descrição clara

Checklist de Qualidade​

Antes de commitar:

  • Código segue convenções de nomenclatura
  • Sem console.log em código de produção
  • Links funcionam corretamente
  • Imagens possuem texto alternativo
  • Markdown formatado adequadamente
  • Build executa sem erros
  • TypeScript compila sem erros

Recursos​

Apêndices​

A. Estratégia de cópia de arquivos​

A estratégia de cópia de arquivos neste projeto tem como objetivo automatizar a sincronização dos arquivos de documentação (README.md e arquivos em docs/) dos seus diretórios de origem para o diretório docs/ utilizado pelo Docusaurus. Isso garante que toda a documentação esteja sempre atualizada e disponível para o site durante o desenvolvimento e a implantação, reduzindo etapas manuais e possíveis erros.

Utilizando um script de cópia (como o scripts/copy-docs.js), o fluxo de trabalho se torna mais eficiente, especialmente ao lidar com múltiplas fontes de documentação ou ao integrar com pipelines de CI/CD.

  1. Configure a variável de ambiente da pasta de origem (no exemplo abaixo, está sendo feito diretamente no terminal)
export DOCS_FOLDER=<sua-pasta-de-documentação>

A pasta de origem deve estar estruturada de tal modo que contenha subpastas, cada uma com a sua documentação:

DOCS_FOLDER
├── service-a/
|       ├───── README.md
|       └───── docs/
...
└── service-b/
        ├───── README.md
        └───── docs/
  1. Execute o script de cópia
npm run copy-docs

Isso irá copiar os arquivos de documentação para os locais de destino apropriados.

  1. Verifique a cópia

Confira os diretórios criados para garantir que os arquivos foram copiados corretamente.

  1. Automatize se necessário

O script copy-docs.js pode ser incluído em outros scripts npm, como prebuild, build ou start, para garantir que a cópia seja feita automaticamente sempre que necessário.

Com essa configuração, sua documentação estará sempre atualizada e pronta para desenvolvimento local ou implantação.

B. Mecanismo de Busca Local​

O projeto utiliza um mecanismo de busca local para facilitar a navegação e localização de conteúdos na documentação, sem depender de serviços externos. A busca é alimentada automaticamente durante o build do Docusaurus, indexando títulos, textos e metadados dos arquivos Markdown e MDX.

Principais Características​

  • Busca instantânea: Resultados aparecem conforme o usuário digita, sem recarregar a página.
  • Indexação local: Todo o conteúdo é indexado no momento do build, garantindo privacidade e performance.
  • Suporte multilíngue: A busca respeita o idioma selecionado pelo usuário, exibindo resultados relevantes em português ou inglês.
  • Integração transparente: O campo de busca está disponível no topo do site, integrado ao tema padrão do Docusaurus.

Como funciona​

O mecanismo de busca é implementado via plugin local, dispensando dependências externas como Algolia. O índice de busca é gerado automaticamente e armazenado junto aos arquivos estáticos do site, permitindo que a busca funcione mesmo em ambientes offline ou restritos.

Customização​

Para ajustar o comportamento da busca (quais campos indexar, idioma, etc.), edite a configuração do plugin no arquivo docusaurus.config.ts.

Referências​

Powered by Caveo 🚀