Ir para o conteúdo principal

Apresentando o Docusaurus

· Leitura de 9 minutos
Joel Marcey

Introdução ao Slash

Estamos muito felizes em apresentar o Docusaurus para ajudá-lo a gerenciar um ou vários sites de código aberto.

Criamos o Docusaurus pelos seguintes motivos:

  1. Para colocar o foco em escrever uma boa documentação, em vez de se preocupar com a infraestrutura de um site.
  2. Para fornecer recursos que muitos de nossos sites de código aberto precisam, como suporte de blog, pesquisa e controle de versão.
  3. Para facilitar o envio de atualizações, novos recursos e correções de bugs para todos ao mesmo tempo.
  4. E, finalmente, para fornecer uma aparência consistente em todos os nossos projetos de código aberto.

Docusaurus é uma ferramenta projetada para tornar mais fácil para as equipes publicar sites de documentação sem ter que se preocupar com a infraestrutura e detalhes de design. Basicamente, tudo o que um usuário precisa fornecer são arquivos de documentação escritos em markdown, personalização de uma página inicial fornecida escrita em React e algumas modificações de configuração. O Docusaurus lida com o resto fornecendo estilos padrão, formatação de site e navegação simples em documentos. Começar é fácil, pois os usuários podem instalá-lo usando npm ou yarn por meio de um script de inicialização simples que cria um site de exemplo funcional pronto para uso .

O Docusaurus também fornece o núcleo web e recursos de documentação completos, incluindo o suporte a blog, internacionalização, buscae versão. Embora alguns projetos possam não exigir nenhuma dessas características, habilitá-los geralmente é uma questão de atualizar as opções de configuração ao invés de ter que adicionar a infraestrutura desde o início. À medida que mais recursos são adicionados ao Docusaurus, os usuários podem atualizar facilmente para a versão mais recente. Isso pode ser feito simplesmente executando o npm ou o yarn update e atualizando as opções de configuração. Os usuários ou equipes não precisarão mais refazer manualmente toda a infraestrutura do seu site cada vez que um novo recurso for adicionado.

O Nascimento do docusaurus#

Nascimento do Slash

Quando o Facebook começou seu programa de código aberto, muitas equipes implementaram um site personalizado para cada um de seus projetos de código aberto. Esta abordagem apresentou desafios quando foi solicitada à equipe de código aberto para ajudar as equipes de projeto a melhorar sua documentação. Como cada site era único, adicionar uma infraestrutura básica, como um blog, navegação consistente, busca, etc. tornou-se um desafio de empreendimento.

A equipe de código aberto tentou ajudar a mitigar este problema apresentando um modelo padrão, baseado em Jekyll, que poderia ser usado como ponto de partida para um site de projeto. Pedimos aos nossos novos projetos para copiar manualmente nossa fonte de templates para o seu repositório, escrever seus documentos e publicar. Essa abordagem de modelo foi adotada pela maioria dos projetos de código aberto iniciados; alguns projetos existentes até converteram suas implementações de site personalizadas para o novo modelo também.

O problema com a abordagem "copie o template para o seu repositório" é que, mesmo que a plataforma seja consistente, O push de atualizações se torna insustentável em um conjunto inteiro de projetos que já estão usando o modelo. Isto é porque perdemos o controle do template depois que um projeto o copiou para o repositório dele. Os projetos eram livres para modificar o modelo conforme o desejado e aplicar suas próprias características específicas do projeto a ele. Então, enquanto os projetos compartilham a mesma plataforma de geração de site, agora desviaram o suficiente onde não podem aproveitar os novos recursos que adicionamos ao longo do tempo. Não havia maneira fácil de pedir a todos os projetos atuais que "copiassem" uma nova versão do template já que isso pode quebrar seu site existente ou remover recursos que eles adicionaram por conta própria. Em vez disso, teríamos de aplicar manualmente as atualizações a cada projeto. Isso se tornou muito problemático quando os projetos começaram a pedir suporte à nossa equipe para internacionalização dentro do modelo, exigindo mudanças de baixo nível de como o template foi estruturado e gerado.

Portanto, começámos a pensar no que poderíamos fazer para ajudar a mitigar o desafio de manter os sites atualizados e consistentes em todo o nosso portfólio. Também queríamos que vários projetos compartilhassem o mesmo software de geração de site. Nós queríamos que eles começassem com o mesmo modelo, e ainda assim ter a flexibilidade necessária para personalizar e adaptar o tema do site de acordo com as suas necessidades. Eles devem ser capazes de ampliar e personalizar seu site, mas quando atualizamos a infraestrutura subjacente com correções e recursos, o projeto deve ser capaz de atualizar de forma simples e sem nenhuma alteração quebrada.

O Docusaurus nasceu!

No Facebook, Docusaurus nos permite executar diferentes projetos rapidamente com os sites da Web, especialmente para equipes que não têm muita experiência com desenvolvimento web ou querem principalmente que um site básico mostre seu projeto. Docusaurus já oferece suporte a sites que precisam de recursos mais avançados, como internacionalização para Jest e versionamento para React Native. Como diferentes projetos solicitam novos recursos para seus sites, eles são adicionados ao Docusaurus e proporcionados simultaneamente a todos os projetos! Em conjunto, isto acaba por reduzir consideravelmente o trabalho necessário para manter diferentes locais para diferentes projectos. Nossas equipes são capazes de focar em manter seus projetos mais saudáveis, gastando mais tempo adicionando recursos, corrigindo bugs e escrevendo documentação.

Levantando-se e funcionando#

Slash Up and Running

Em sua essência, nós queríamos que os sites que rodam o Docusaurus fossem fáceis de usar. Com um comando de instalação e uma configuração simples de , você realmente pode ter um site em execução padrão.

Quando você executar o docusaurus-init, verá uma estrutura semelhante a:

diretório-raiz├── 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    │   ├── 2017-09-25-testing-rss.md    │   ├── 2017-09-26-adding-rss.md    │   └── 2017-10-24-new-version-1.0.0.md    ├── core    │   └── Footer.js    ├── package.json    ├── pages    ├── sidebars.json    ├── siteConfig.js    └── static

Com exceção de node_modules e package.json, todos os diretórios e arquivos que você vê estão onde você personalizar e adicionar conteúdo ao seu site baseado em Docusaurus. A pasta docs é onde você adiciona seu markdown que representa sua documentação; a pasta de blog é onde você adiciona sua marcação para suas postagens de blog; siteConfig.js é onde você faz a maioria das personalizações para o seu local; sidebars.json é onde você mantém o layout e o conteúdo da barra lateral para sua documentação; a pasta pages é onde você adiciona páginas personalizadas para seu site; a pasta static é para onde vão todos os seus ativos estáticos (por exemplo, folhas de estilo CSS e imagens); e a pasta core é onde você pode personalizar os componentes principais do site, neste caso o rodapé.

Como o Docusaurus funciona?#

O Docusaurus é escrito principalmente em JavaScript e React, substituindo o Jekyll que usamos no template antigo. Usamos o Remarkable para a nossa renderização em markdown e highlight.js para o nosso destaque de sintaxe do bloco de código. O núcleo da funcionalidade do Docusaurus é no diretório lib do Docusaurus repo. A estrutura geral parece com:

diretório-raiz-do-Docusaurus├── lib│   ├── core│   ├── server│   │   ├── generate.js│   │   ├── server.js│   │   └── ...and more files│   ├── static│   ├── build-files.js│   ├── copy-examples.js│   ├── generate-feed.js│   ├── publish-gh-pages.js│   ├── rename-version.js│   ├── start-server.js│   ├── versions.js│   └── write-translations.js

As chaves aqui são build-files.js e start-server.js. Existem muitas semelhanças entre esses dois arquivos: build-files.js é usado para construir os artefatos físicos para servir por um servidor web externo. start-server.js é usado para executar o servidor Docusaurus e testar localmente seu site. Ambos passam pelo seguinte processo geral para pegar todos os markdown e configuração para criar um site executável:

  1. Processe as configurações do seu site em siteConfig.js
  2. Leia os metadados do documento que existem em todos os arquivos markdown no diretório de documentos.
  3. Criar uma tabela de conteúdos para seus documentos com base nos ids extraídos dos metadados.
  4. Converta o markdown para HTML, incluindo a substituição do link.
  5. Esses arquivos irão para o diretório de compilação/documentação do site compilado. e qualquer versão traduzida irá para uma pasta específica do idioma dentro da pasta "build/documentação".
  6. Repita 1-3 para postagens do blog.
  7. O arquivo do blog irá para o diretório "build/blog" do site compilado.
  8. Leia o arquivo main.css e concatene qualquer css definido pelo usuário no arquivo css mestre que estará no diretório build/css do site compilado.
  9. Copiar imagens em um diretório de compilação/imagem do site compilado.
  10. Leve quaisquer páginas personalizadas que foram adicionadas à pasta de páginas do site e compile-as para o diretório de compilação raiz do site compilado. Quaisquer versões traduzidas irão para uma pasta específica do idioma dentro da compilação.
  11. Cria arquivos CNAME e sitemap.xml e adiciona-os à compilação.

Observe que este processo não leva em conta completamente como as traduções ou versão funcionam. Os detalhes subjacentes a esses recursos serão salvos em futuras postagens no blog.

A estrutura final do seu site compilado será parecida como:

build├── website│   ├── CNAME│   ├── blog│   ├── css│   ├── docs│   ├── en│   ├── help.html # página personalizada│   ├── img│   ├── index.html # página principal│   ├── sitemap.xml│   └── users.html # página personalizada

Comunidade#

Docusaurus

Nós saudamos as suas contribuições para o Docusaurus, caso queira usá-las em seu próprio site, você quer contribuir para o núcleo do Docusaurus ou apenas ter perguntas. Siga-nos no GitHub e Twitter.

Agradecimentos#

O Docusaurus não existiria sem o restante do núcleo da equipe Docusaurus: Eric Nakagawa, Hector Ramos, Eric Vicenti e Frank Li — um antigo estagiário no Facebook que implementou as principais tecnologias e recursos.

Agradecimentos especiais também aos nossos primeiros adotantes do Docusaurus:

Sem a dedicação deles em criar ou migrar seus sites para a plataforma, não estaríamos na posição em que estamos hoje.

Recursos#