Documentação fácil com o Docusaurus

O que acontece quando você mistura a facilidade e flexibilidade do Markdown; o poder da componentização provido pelo React; um sistema de versionamento fácil; procura por documentos no melhor estilo Google e uma dinossaura baixinha muito simpática? Você tem o Docusaurus, a plataforma de documentação de código aberto, desenvolvida pelo time de projetos abertos do Facebook, que já possui mais de 6.700 estrelas no GitHub e está disponível sob a licença MIT.

O projeto é estrelado pela mascote Slash, criação da equipe de engenheiros do projeto, e faz referência ao // ou /* ou /// que é utilizado sempre que queremos fazer comentários (documentação) no código. Sua curiosa história é contada aqui. Ele já é utilizado por diversas empresas e projetos, como o Jest, React-Native, ReasonML, Almin, BuckleScript, Vuls e o próprio Docusaurus!

Desde a sua concepção, o Docusaurus foi projetado para ser uma plataforma de documentação fácil de se instalar e se integrar bem a qualquer projeto. Para utilizá-lo, é necessário executar o seguinte comando no terminal:

npm install --global docusaurus-init
// ou
yarn global add docusaurus-init

Isso fará com que a ferramenta seja instalada. Uma vez feito, basta executar o seguinte comando na raiz do projeto em que você quer utilizá-lo:

docusaurus-init

Este comando irá instalar toda a estrutura necessária para que a documentação seja construída. Quando concluído, seu projeto terá a seguinte estrutura (além dos arquivos que já existiam):

raiz-do-repositorio
├── docs-examples-from-docusaurus
│   └── doc1.md
│   └── doc2.md
│   └── doc3.md
│   └── exampledoc4.md
│   └── exampledoc5.md
└── website
│   └── blog-examples-from-docusaurus
│       └── 2016-03-11-blog-post.md
│       └── 2017-04-10-blog-post-two.md
│   └── core
│       └── Footer.js
│   └── node_modules
│   └── package.json
│   └── pages
│   └── sidebars.json
│   └── siteConfig.js
│   └── static

Na estrutura criada, troque o nome do diretório docs-examples-from-docusaurus para docs e na pasta website, de blog-examples-from-docusaurus para blog. Dado isso, execute o comando npm start (ou yarn start) no diretório website. Se tudo estiver correto, no http://localhost:3000, veremos o exemplo da documentação carregada.

Sua estrutura é bem simples:

• website/core/Footer.js: Este arquivo corresponde ao footer das páginas. Podemos customizá-los para colocar as informações que sejam coerentes com o projeto.
• website/blog-examples-from-docusaurus: Nesta pasta estão alguns exemplos que servirão de base para o programador criar postagens para o blog interno utilizando o Markdown.
• docs-examples-from-docusaurus: Aqui estão os arquivos que vão corresponder a documentação.
• website/pages: Este diretório contém exemplos de páginas de nível superior (top level) para o site.
• website/static: Como o nome sugere, é neste diretório onde ficam armazenados todos os assets do projeto.
• website/siteConfig.js: Este arquivo é extremamente importante. É nele que definimos as configurações globais da nossa documentação. Coisas como: cores, fontes, favicon, copyright, url, etc.

Todas as configurações estão disponíveis aqui.

Note que no diretório website nós também temos o diretório i18n. Aqui ficarão os arquivos responsáveis pela internacionalização da nossa documentação. Por definição, somente o en.json é criado, mas fica a nosso critério criar os demais que sejam necessários. Todos os passos necessário estão muito bem explicados aqui.

Essa estrutura inicial é só para dar um gostinho do potencial e facilidade da plataforma. Na página da documentação você encontrará todos os detalhes citados aqui e muito mais, desde como preparar, criar e publicar seu site; como administrar o blog, configurar o sistema de busca, tradução e versionamento. Além disso, há também detalhes do funcionamento da API e comandos.

Se for do interesse, comentem abaixo que terei o maior prazer em criar artigos mais completos sobre como configurar e subir toda a plataforma do Docusaurus.

Experimente a ferramenta e pare de dar desculpas para não documentar seu projeto!

Versão em Vídeo

Você também pode acompanhar todos os passos que foram feitos no vídeo abaixo!