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!