Docusaurus foi anunciado oficialmente há mais de nove meses como uma forma de construir facilmente sites de documentação de código aberto. Desde então, ele acumulou mais de 8.600 estrelas no GitHub e é usado por muitos projetos de código aberto populares, como React Native, Babel, Jest, Reason e Prettier .
Há um ditado que diz que o melhor software está em constante evolução, e o pior não. Caso você não saiba, estamos planejando e trabalhando na próxima versão do Docusaurus 🎉.
Introdução
Tudo isso começou com esta questão RFC aberta por Yangshun no final de junho de 2018.
[RFC] Docusaurus v2 · Issue #789 · facebook/docusaurus
These are some of the problems I'm seeing in Docusaurus now and also how we can address them in v2. A number of the ideas here were inspired by VuePress and other static site generators. In the current static site generators ecosystem, t...
A maioria das melhorias sugeridas são mencionadas na edição; Fornecerei detalhes sobre alguns dos problemas na Docusaurus 1 e como iremos tratá-los na Docusaurus 2.
Infraestrutura
Conteúdo
De fato, um site Docusaurus 1 foi construído em um monte de páginas HTML estáticas. Apesar de usar o React, não estávamos usando completamente os recursos oferecidos pelo React, como o estado do componente, que permite páginas dinâmicas e interativas. React só foi usado como um mecanismo de template para conteúdo estático e a interatividade precisa ser adicionada através de tags de script e dangerouslySetInnerHTML😱.
Além disso, não existe uma maneira fácil de mudar como o Docusaurus carrega o conteúdo. Por exemplo, adicionar pré-processadores CSS como Sass e Less não era suportado nativamente e envolveu muitos hacks de usuários para adicionar scripts personalizados.
Para o Docusaurus 2, usaremos webpack como um pacote de módulos e estamos mudando a maneira como servimos o conteúdo. Adicionar os pré-processadores CSS será tão fácil quanto adicionar um carregador webpack. Em vez de um HTML estático puro, durante o tempo de compilação criaremos uma versão renderizada pelo servidor e renderizaremos o HTML correspondente. Um site Docusaurus será essencialmente uma aplicação isomorphic/universal. Esta abordagem é fortemente inspirada pelo Gatsby.
Versionamento
Se você já usa o Docusaurus há um tempo. você pode notar que o Docusaurus cria a documentação versionada se, e somente se o conteúdo da documentação for diferente.
Por exemplo, se temos docs/hello.md:
---
id: hello
title: hello
---
Hello world !
E cortamos a versão 1.0.0, o Docusaurus criará versioned_docs/version-1.0.0/hello.md:
---
id: version-1.0.0-hello
title: hello
original_id: hello
---
Hello world !
No entanto, se não houver mudanças no hello.md ao cortar v2.0.0, o Docusaurus não criará nenhuma documentação versionada para esse documento. Em outras palavras, versioned_docs/version-2.0.0/hello.md não existe.
Isso pode ser muito confuso para os usuários; se eles quiserem editar a documentação v2.0.0, eles precisam editar versioned_docs/version-1.0.0/hello.md ou adicionar manualmente versioned_docs/version-2.0.0/hello.md. Isso poderia potencialmente levar a erros indesejados. Aqui está um cenário real no Jest.
Além disso, isto aumenta a complexidade dentro da base de código, uma vez que necessitamos de um mecanismo para as quedas de versão. E durante o tempo de construção, o Docusaurus precisa substituir o link da versão correta. Essa também é a causa de um bug onde renomear a documentação quebra links em versões antigas.
Para o Docusaurus 2, toda vez que recortarmos uma nova versão, ao invés disso, faremos um snapshot de toda a documentação. Não vamos exigir que o conteúdo de um documento tenha sido alterado. Esta é uma troca de complexidade de espaço para um melhor desenvolvedor e experiência de usuário. Utilizaremos mais espaço para uma melhor separação das preocupações e para garantir a correcção.
Tradução
O Docusaurus permite fácil funcionalidade de tradução usando Crowdin. Os arquivos de documentação escritos em inglês são enviados ao Crowdin para serem traduzidos por usuários dentro de uma comunidade. Sempre assumimos que Inglês é o idioma padrão, mas este pode não ser o caso para todos os usuários. Temos visto muitos projetos não-ingleses em código aberto usando o Docusaurus.
Para o Docusaurus 2, nós não assumiremos que o inglês seja o idioma padrão. Quando um usuário habilita internacionalização, eles precisam definir o idioma padrão no siteConfig.js. Nós então assumiremos que todos os arquivos da docs são escritos nessa linguagem.
Além disso, depois de trabalhar no MVP do Docusaurus 2, eu percebi que é possível não usar Crowdin para traduções. Assim, podemos precisar adicionar um fluxo de trabalho adicional para permitir esse cenário. No entanto, ainda recomendaremos fortemente que as pessoas usem o Crowdin para facilitar a integração.
Personalização
Layout
O estado atual do Docusaurus é que ele está encarregado de todo o layout e estilo, involuntariamente tornando muito difícil para os usuários personalizar a aparência de seu site para seus desejos.
Para o Docusaurus 2, layout e estilo devem ser controlados pelo usuário. O Docusaurus irá lidar com a geração de conteúdo, roteamento, tradução e versão. Inspirado por create-react-app e VuePress, O Docusaurus ainda fornecerá um tema padrão, do qual o usuário pode ejetar, para mais layout e personalização de estilo. Isto significa que é muito possível para o usuário até alterar o meta HTML usando React Helmet. Temas baseados na comunidade também são possíveis. Essa abordagem de permitir que os usuários sejam responsáveis pelo layout e estilo é adotada pela maioria dos geradores de sites estáticos.
Markdown
Nossa parser markdown atualmente é alimentado por Remarkable. E se o usuário quiser usar markdown-it ou até mesmo MDX? E então há um problema de qual realçador de sintaxe deve ser usado (por exemplo: Prism vs Highlight.js). Deveríamos deixar essas escolhas abertas ao utilizador.
Para o Docusaurus 2, os usuários podem ejetar e escolher seu próprio parser markdown. Não importa se eles querem usar outro analisador markdown, como Remark, ou até mesmo seu próprio analisador markdown. Como regra geral, o usuário tem que fornecer um componente React, no qual forneceremos um objeto filho contendo a string RAW do markdown. Por padrão, usaremos o Remarkable para o analisador markdown e o Highlight.js para o realce de sintaxe. O parser padrão ainda pode mudar no futuro, uma vez que ainda estamos experimentando diferentes parsers markdown.
Pesquisar
Nossa funcionalidade principal de busca é baseada no Algolia. Existem solicitações de usuários para poder usar diferentes ofertas de pesquisa, como lunrjs para pesquisa off-line.
Pessoalmente, gosto do Algolia, e temos uma grande experiência a trabalhar com eles. Eles são muito responsivos; podemos facilmente enviar uma pull request para Algolia, já que sua DocSearch é de código aberto. Por exemplo, eu apresentei recentemente este PR que permite que o DocSearch alterne idiomas no mapa do site.
Para o Docusaurus 2, vamos permitir que os usuários personalizem a caixa de pesquisa. Os usuários simplesmente precisam ejetar do tema padrão e modificar a interface de pesquisa (um componente React). No entanto, ainda usaremos o Algolia no tema padrão.
Estabilidade
O software nunca será perfeito, mas nós queremos que o Docusaurus não quebre conforme adicionamos novos recursos. Quando o Docusaurus foi liberado pela primeira vez, ele não tinha nenhuma suite automatizada de teste. Como resultado, houve muitas regressões que não foram detectadas previamente. Embora tenhamos recentemente adicionado uma série de testes, a cobertura de testes ainda é relativamente baixa.
Para o Docusaurus 2, estamos adicionando testes à medida que desenvolvemos já que vamos fazer uma reescrita nova. Por isso, eu acredito que deveria estar mais estável do que nunca e deveria ser mais difícil quebrar coisas do que o Docusaurus 1.
Perguntas Frequentes
Haverá alterações significativas?
Se você leu o post até este ponto, deve ser capaz de notar que haverá mudanças significativas. Embora tentemos minimizar o número de alterações de interrupção e torná-lo compatível com versões anteriores, tanto quanto possível, acreditamos que algumas alterações de interrupção são necessárias. Isso se deve principalmente ao fato de o Docusaurus 2 ser uma grande reescrita e re-arquitetura da base de código.
A lista exata de quebra de alterações não é ainda totalmente conhecida, pois o desenvolvimento não está 100% finalizado. No entanto, uma coisa que eu destacarei é que vamos depreciar muitas opções no siteConfig.js e nós planejamos mantê-lo o mais flexível possível. Por exemplo, cleanUrl do siteConfig será descontinuado, pois todos os URLs para sites Docusaurus 2 estarão sem o sufixo .html.
Nosso objetivo é que a maioria dos sites devem ser capazes de atualizar para o Docusaurus 2 sem muita dor. Também incluiremos um guia de migração quando liberarmos o Docusaurus 2. Quando chegar o momento, sinta-se à vontade para entrar em contato no Discord ou no Twitter para perguntar e obter ajuda.
Quando é o lançamento do Docusaurus 2?
A partir de agora, não temos uma data exata prevista para a libertação. Pessoalmente, penso que talvez possamos libertar uma versão alfa nos próximos um a dois meses. mas isto não passa, evidentemente, de uma estimativa.
Uma coisa que eu gostaria de compartilhar é que, enquanto Docusaurus faz parte do Facebook Open Source e a maioria da equipe são funcionários do Facebook, o trabalho de manutenção e desenvolvimento é realizado principalmente fora do horário de trabalho normal. Eu sou atualmente um aluno do último ano de graduação em NTU Singapore, então tive que conciliar entre fazer meu trabalho de curso, meu projeto do último ano e manter/desenvolver o Docusaurus. No entanto, isso não significa que não queremos tornar o Docusaurus melhor. Na verdade, queremos torná-lo o mais incrível possível.
Por enquanto, o verdadeiro trabalho do Docusaurus 2 ainda está hospedado em um repositório privado. Num futuro próximo, vamos movê-los para o repositório público. Quando essa altura chegar, encorajo todos a analisá-la e espero que contribuam de alguma forma. Antes disso, fique ligado 😉!
Considerações Finais
O Docusaurus teve um grande impacto na comunidade de código aberto como visto por muitos projetos populares que usam o Docusaurus para documentação. Para avançarmos mais rapidamente no futuro, estamos aproveitando a oportunidade para resolver alguns problemas fundamentais com o Docusaurus 1 e nos esforçar para melhorar o Docusaurus para todos. Na verdade, é seguro dizer que o Docusaurus 2 não é apenas um plano; o seu trabalho foi iniciado e, assim o esperamos, poderemos vê-lo concretizado num futuro próximo.
A missão do Docusaurus sempre foi tornar realmente fácil para você ter um site com a documentação pronta e acabando. Essa missão não muda com o Docusaurus 2.
Também queremos que as pessoas saibam que devido ao trabalho no Docusaurus 2, vamos aceitar menos as novas funcionalidades/grandes mudanças no Docusaurus 1.
Se você estiver usando o Docusaurus, você é parte da nossa comunidade; deixe-nos saber como podemos melhorar o Docusaurus para você. Se você gostou do trabalho que estamos fazendo, você pode apoiar o Docusaurus no Open Collective.
Se estiver patrocinando nosso trabalho no Open Collective, pessoalmente lhe oferecemos a mão para a manutenção e melhoria do site do Docusaurus.
Por último, se você ainda não fez isso, clique no botão estrela e relógio no GitHub, e siga-nos no Twitter.