🙈 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?