4
ofabiodev
2 min de leitura ·

🙈 Pitch: Passei mais tempo configurando a documentação do que escrevendo ela

Toda vez que começava um projeto novo, eu queria apenas criar alguns arquivos Markdown e publicar uma documentação organizada. Mas acabava encontrando configurações, temas, plugins, ferramentas de build e decisões demais para uma tarefa que deveria ser simples.

Foi para resolver essa dor que criei o docshelf.

A proposta é transformar uma pasta de Markdown em um site de documentação estático, sem exigir uma estrutura enorme para começar:

npm install -D docshelf
npx docshelf init
npx docshelf dev

Depois, basta escrever os arquivos dentro de docs/:

docs/
├── index.md
├── getting-started.md
└── guides/
    └── configuration.md

Quando estiver pronto:

npx docshelf build

A pasta dist/ gerada pode ser publicada no GitHub Pages, Cloudflare Pages, Netlify ou em qualquer outro serviço que hospede arquivos estáticos.

O docshelf já suporta:

  • Busca client-side
  • Tema claro, escuro e automático
  • Sidebar, breadcrumbs e navegação entre páginas
  • Syntax highlighting
  • Callouts, tabs e accordions
  • Cards, steps e code groups
  • Tabelas, version badges e atalhos de teclado
  • Imagens e vídeos
  • Sitemap e RSS
  • SEO, Open Graph e JSON-LD
  • Validação de frontmatter
  • Verificação de links quebrados e assets ausentes
  • Watch mode para atualizar o site durante o desenvolvimento
  • Ícones (Do pacote Phosphor Icons) e SVGs personalizados
  • Configuração em docshelf.toml
  • CSS personalizado em public/custom.css

Também existe o comando:

npx docshelf check

Ele verifica problemas antes do deploy, como frontmatter inválido, links internos quebrados, imagens ausentes e componentes desconhecidos.

A documentação do próprio projeto foi feita usando o docshelf:

Ver a documentação

O código está disponível no GitHub:

Ver o projeto

O projeto ainda está em desenvolvimento e quero melhorar principalmente a experiência do CLI, a configuração e os componentes.

Se você já usa alguma ferramenta de documentação, qual parte mais te incomoda hoje? E o que faria você trocar para uma ferramenta mais simples?

Carregando publicação patrocinada...
1

Para mim, o maior custo não é criar o primeiro site de documentação, mas impedir que ele se afaste do produto depois de algumas versões. Eu consideraria trocar de ferramenta se essa verificação fizesse parte do build: links e âncoras quebrados, assets ausentes, exemplos executáveis quando possível, versões, canonical/hreflang entre idiomas e uma falha clara no CI.

Outro diferencial seria o preview reproduzir exatamente o resultado estático e mostrar, antes do deploy, alterações na navegação e nos metadados. O docshelf check já parece ir na direção certa. Talvez valha separar erros que devem interromper o build de avisos editoriais e permitir regras por projeto. Isso preservaria a simplicidade sem transformar a configuração em outro framework.

1
1
1

Parabéns pelo projeto! A proposta do docshelf ataca uma dor real: ferramentas consolidadas como Docusaurus ou VitePress são excelentes, mas o overhead de plugins, dependências pesadas e configuração de tema muitas vezes desvia o foco do que realmente importa, que é apenas escrever a documentação.
Respondendo às suas perguntas:
O que mais incomoda hoje nas ferramentas existentes:
A fragilidade de build quando a documentação cresce. Um link quebrado ou um frontmatter com syntax error muitas vezes estoura o build do CI sem apontar com clareza o arquivo e a linha do problema.
O que me faria adotar o docshelf:
O comando docshelf check que você incluiu é um dos maiores diferenciais. Poder rodar uma validação prévia de links e assets no CI antes do deploy é excelente.
Zero-config real para arquivos Markdown padrão: conseguir apontar a ferramenta para uma pasta docs/ já existente (com ADRs, guias e RFCs) e ela renderizar sem exigir que eu adapte a estrutura ou use sintaxes proprietárias.
Performance de build ultrarrápida para repositórios com dezenas de páginas.
A interface e a tipografia da documentação oficial ficaram muito limpas. Sucesso no desenvolvimento!