DoDocs

O DoDocs, como o nome diz, faz documentos. Esse projeto recebe uma pasta com arquivos .md e .mdx e devolve um site de documentação estático, com navegação lateral, busca, sumário, realce de sintaxe, tema claro e escuro e links de anterior e próximo. Quem usa não escreve nenhuma linha de código de aplicação. A árvore de pastas do repositório é o que define a árvore do site.

Publicar documentação costuma exigir escolher um framework, configurar um site e manter um build. Esse trabalho a mais é o que faz o texto ficar no README ou não sair do lugar. Com o DoDocs, a documentação continua sendo Markdown puro, versionada ao lado do código, no mesmo commit da mudança que ela descreve, e publicar é adicionar uma GitHub Action apontada para a pasta.

Conheci esse tipo de gerador na documentação do Zustand, a biblioteca de gerenciamento de estado do coletivo Poimandres. A página tinha o que eu queria nos meus projetos: barra lateral montada a partir das pastas, busca no navegador, sumário e leitura confortável em tema claro e escuro. Quem constrói aquele site é o pmndrs/docs, o gerador que o coletivo usa nas próprias bibliotecas.

O DoDocs é um fork desse gerador, sem as partes que só serviam ao Poimandres, e hoje segue caminho próprio. A licença MIT e o copyright originais estão preservados no repositório.

Conceitos fundamentais

Conceito	O que é
Markdown	Formato de texto simples com marcação leve (# para título, ** para negrito), que vira HTML na hora de publicar.
MDX (Markdown + JSX)	Markdown que também aceita componentes dentro da página, como <Mermaid> ou <Hint>.
SSG (Static Site Generation, geração de site estático)	O site inteiro é gerado em arquivos HTML no momento do build; não existe servidor de aplicação respondendo requisição.
fork (bifurcação)	Cópia de um projeto de código aberto que passa a evoluir por conta própria, mantendo licença e crédito da origem.
GitHub Action	Automação que roda no GitHub a cada push; aqui, é ela que constrói o site e o publica.
workflow reutilizável	Automação escrita uma vez e chamada por outros repositórios, que passam só os parâmetros. Evita copiar o mesmo YAML em cada projeto.
GitHub Pages	Hospedagem estática gratuita do GitHub, servida direto do repositório.
imagem Docker	Pacote fechado com o gerador e todas as suas dependências; roda igual na sua máquina e no servidor do GitHub.
frontmatter	Bloco de metadados no topo do arquivo Markdown (título, descrição, ordem), delimitado por ---.
interface do site	Os textos que o gerador coloca na tela, não os seus: caixa de busca, “Nesta Página”, rótulos de anterior e próximo.
cor de destaque	Uma única cor da qual a paleta inteira é derivada, para tema claro e escuro, sem escolher cor a cor.
llms.txt	Arquivo padronizado que lista as páginas do site em texto puro, para modelos de linguagem lerem a documentação sem precisar extrair o texto do HTML.

Stack

Nenhum arquivo de configuração descreve o site. Não existe rota nem índice para manter em dia: criar um arquivo cria uma página, e mover um arquivo move a página.

Arquitetura

1. A pasta define o site

Um índice escrito à mão precisa ser atualizado toda vez que um arquivo entra, sai ou muda de lugar. A árvore de diretórios já tem essa informação, então é ela que o DoDocs lê:

docs/
├── getting-started/
│   ├── introduction.md
│   └── configuration.md
└── writing/
    └── markdown.md

Essa árvore é exatamente a barra lateral. Duas pastas viram duas seções, três arquivos viram três páginas, e o caminho do arquivo vira a URL. Uma pasta sem página própria manda o leitor para a primeira página dentro dela, em vez de responder 404.

Quando o padrão não serve, dois parâmetros ajustam a barra lateral. O nav_order define a ordem das pastas e agrupa pastas sob um rótulo. O nav_labels corrige nomes que a capitalização automática erra, como sql virar “Sql” quando deveria ser “SQL”. Dentro de uma pasta, a chave nav no frontmatter de cada página decide quem vem primeiro. Nenhum dos três é obrigatório.

2. Publicar: uma Action e uma imagem Docker

Não existe pacote para instalar. O repositório que quer documentação adiciona um arquivo de workflow, aponta para a pasta e recebe o site no GitHub Pages a cada push na main:

jobs:
  build:
    permissions:
      contents: read
      pages: write
      id-token: write
    uses: thiagocajadev/do-docs/.github/workflows/build.yml@main
    with:
      mdx: "docs" # sua pasta de Markdown
      libname: "Meu Projeto" # nome exibido no cabeçalho
      home_redirect: "/getting-started/introduction"
      locale: "pt-BR" # 'en' (padrão) ou 'pt-BR'
      icon: "📘"

O build.yml do DoDocs é um workflow reutilizável: o repositório consumidor não copia lógica de build, apenas preenche os parâmetros. Só três são obrigatórios (mdx, libname e home_redirect), e o resto tem padrão razoável.

Por baixo, esse workflow monta a sua pasta de documentação dentro do contêiner ghcr.io/thiagocajadev/do-docs e roda o build lá. A versão do gerador fica fixada na tag da imagem (docker_tag, padrão 3), então uma mudança no DoDocs não reescreve o seu site sem você pedir. Toda opção existe em dois formatos, entrada da Action em minúsculas (theme_primary) e variável de ambiente em maiúsculas (THEME_PRIMARY), porque são a mesma coisa escrita de dois jeitos.

Antes de configurar a Action, dá para ver o resultado na sua máquina. O script de preview usa a mesma imagem Docker, e nada é instalado localmente:

curl -sL https://raw.githubusercontent.com/thiagocajadev/do-docs/refs/heads/main/preview.sh | \
  MDX="docs" \
  ICON="🥑" \
  DOCKER_IMAGE="ghcr.io/thiagocajadev/do-docs:latest" \
  sh

3. .md ou .mdx

As duas extensões funcionam na mesma pasta, misturadas. A escolha muda o que o arquivo tem permissão de fazer:

Extensão	Use quando	O que você ganha
.md	Markdown comum, o caso da maioria	Todo o Markdown do GitHub, mais HTML bruto como <details>
.mdx	A página precisa de um componente	Tudo do .md, mais <Intro>, <Hint>, <Mermaid> e afins

Na dúvida, .md. Renomeie para .mdx no dia em que precisar de um componente, sem mexer no conteúdo. A diferença prática aparece no HTML: em .md, escrever <div> produz uma div de verdade; em .mdx, uma tag com inicial maiúscula é lida como componente, e o HTML bruto precisa ser válido para JSX (a sintaxe do React, mais rígida que a do HTML).

Os componentes cobrem o que documentação técnica costuma pedir: <Intro> abre a página, <Hint> destaca um aviso, <Keypoints> lista o que a página cobre, <Mermaid> desenha diagramas a partir de texto, e <Contributors> busca no GitHub quem editou aquele arquivo. Os alertas do GitHub ([!NOTE], [!WARNING]) funcionam direto no .md, sem componente.

4. Um tema gerado de uma cor, uma interface em dois idiomas

O DoDocs pede uma cor só, o theme_primary, e deriva a paleta inteira dela com o react-mcu, que implementa o Material Color Utilities do Google. Quem publica um texto não escolhe cor a cor para tema claro e escuro: as duas variantes saem da mesma origem, e o alternador oferece claro, escuro e “seguir o sistema”. Quem escreve HTML solto na página usa as classes do tema (text-on-surface-variant, por exemplo) e acerta os dois modos.

O locale decide o idioma da interface do site, ou seja, dos textos que o DoDocs coloca na tela: a busca, o “Nesta Página”, os rótulos de anterior e próximo, o alternador de tema e o rodapé. Aceita en (padrão) e pt-BR, e um valor desconhecido cai para o inglês em vez de quebrar o build. O seu conteúdo nunca é traduzido: o DoDocs renderiza o Markdown no idioma em que ele foi escrito.

Mais duas peças ajudam quem chega ao site publicado:

• Busca no navegador. O índice é um JSON gerado no build e servido junto com o site. A tecla / abre a caixa de busca, e a ordenação por proximidade tolera erro de digitação. Não há serviço de busca para hospedar nem chave de acesso para guardar.
• llms.txt e llms-full.txt. Duas rotas estáticas listam as páginas e entregam o conteúdo em texto puro, no formato que modelos de linguagem consomem sem precisar extrair o texto do HTML.

5. O que mudou em relação ao projeto de origem

O DoDocs começou como fork do pmndrs/docs, e boa parte do trabalho foi remover o que só servia ao projeto de origem. O gerador original atendia às bibliotecas do Poimandres, e carregava peças presas a esse contexto.

• Saiu o que era do Poimandres. O servidor MCP (Model Context Protocol, protocolo que entrega dados a modelos de linguagem), o índice das bibliotecas do coletivo, os sandboxes React e os favicons que apareciam em todo site gerado.
• A barra lateral passou a servir qualquer projeto. Navegação recursiva em qualquer profundidade, com ordem, agrupamento e nomes de exibição configuráveis. Pasta sem página própria leva à primeira página de dentro, no lugar do 404.
• A interface ganhou português. Os textos do gerador, nunca o conteúdo de quem escreve.
• A operação ficou mais simples. Uma imagem Docker publicada e um workflow reutilizável, no lugar de clonar e compilar o gerador.

O manual do DoDocs é construído pelo próprio DoDocs, pelo mesmo build.yml que os outros repositórios chamam. Um erro na navegação ou no tema aparece primeiro na documentação do projeto, antes de chegar em quem usa.

Convenções

• Código em inglês, incluindo identificadores e nomes de arquivo. Os textos da interface vivem em src/i18n, em um mapa por idioma.
• Testes onde o Markdown vira página: a compilação do MDX, a reescrita de links e a resolução de URL das imagens. Um erro nessas três peças quebra o site de todo repositório que usa o DoDocs.
• Release por número de versão: subir o version do package.json faz a integração contínua publicar a imagem Docker e criar as tags v<major> e v<major>.<minor>.<patch>.
• A documentação acompanha o repositório dela. Nenhum projeto que usa o DoDocs precisa de repositório separado para documentar.

Status

Aspecto	Estado
Maturidade	Em uso, evolução iterativa
Cobertura de testes	Unit (Vitest) na compilação MDX, nos links e nas imagens
Disponibilidade	Documentação publicada no GitHub Pages
Repositório	Público, licença MIT
Monetização	Nenhuma, ferramenta de código aberto

Quem usa o DoDocs aceita o layout que ele gera e, em troca, não mantém um site. Se você quer a sua versão, com o seu tema e os seus componentes, fica o convite: o repositório é público e sob licença MIT, então faça seu fork.