Como converti o Perfil para o Docusaurus em menos de 2 horas

“Joel e eu estávamos discutindo sobre ter um site e como teria sido ótimo lançar com ele. Então, eu me desafiei a adicionar suporte ao Docusaurus. Demorou pouco mais de uma hora e meia. Vou enviar-lhe um PR para que possa dar uma olhada e ver se gosta. Seu fluxo de trabalho para adicionar documentos não seria muito diferente da edição desses arquivos markdown.”

— Nota enviada para a equipe Profilo

Esta é a história da curta viagem que levou para criar o site de Perfil usando o Docusaurus.

Profilo, uma biblioteca Android para coletar rastros de desempenho da produção, foi anunciada no início deste ano. O projeto foi publicado no GitHub com menos de alguns arquivos ou Markdown para descrever sua funcionalidade e nenhum site para mostrar qualquer marca e destacar o logotipo. A tarefa em questão era transformar a documentação e o logotipo existentes num site.

Em geral, ao criar um site com o Docusaurus você faz o seguinte:

1. Gere um site de modelos usando scripts do Docusaurus.
2. Personalize os arquivos de modelo gerados para as cores do site desejado e a configuração do seu projeto (ex: site e links do GitHub).
3. Crie o conteúdo do site:
   1. Adicionar seus documentos e quaisquer ativos de suporte.
   2. Personalize a página inicial padrão fornecida pelo Docusaurus para atender às suas necessidades.
   3. Configurar o arquivo padrão de navegação do site.
4. Publique o site e configure como ele será publicado para alterações futuras.

Dado que tenho arquivos Markdown pré-existentes, Não precisei gerar o conteúdo do núcleo, mas tenha certeza de que o Docusaurus possa processar os arquivos, adicionando os metadados esperados. A maior parte do trabalho consistiria, portanto, em personalizar os padrões fornecidos pelo Docusaurus.

Visão geral de passos realizados

Aqui está uma visão geral das etapas tomadas para converter um site. Discutirei alguns dos aspectos do design em uma seção posterior.

Design e cores:

1. Obteve todos os formatos de logo desejados pelo designer. Precisei criar o .favicon.
2. Trabalhou algumas cores do site primário e secundário passáveis usando as ferramentas http://paletton.com/ - muito útil!

Configuração inicial do site:

1. Forked o projeto de perfil no GitHub e criou um clone local do fork para configurar o site.
2. Criou o site inicial do Docusaurus usando as instruções de instalação.
3. Excluído as pastas docs-examples-from-docusaurus e website/blog-examples-from-docusaurus, já que estas não seriam necessárias. O perfil tinha documentos existentes que poderíamos usar e não havia necessidade de blogs neste momento.

Criação de conteúdo:

1. Adicionados metadados aos arquivos Markdown existentes encontrados na pasta docs, por exemplo:

   +---+id: architecture+title: Architecture+sidebar_label: Architecture+---

2. Adicionado o logo assets na pasta website/static/img.

3. Modificado website/pages/en/index.js, a página inicial, para destacar recursos de perfil.

4. Modificado website/core/Footer.js, o rodapé, para simplificá-lo para o Profilo.

5. Editado website/siteConfig.js (arquivo de configuração do site) para especificar as cores primárias e secundárias escolhidas anteriormente.

6. Modificado o website/sidebars.json que especifica a navegação na barra lateral. Listando todos os documentos e personalizados com base nos metadados adicionados aos arquivos Markdown.

7. Editado o arquivo de configuração do site para especificar as propriedades do GitHub, imagens do logotipo, links de cabeçalho e o link do site.

8. Estado o site localmente durante esta fase. (Eu executei yarn start na pasta site para iniciar o servidor.)

Comentários e revisar as alterações:

1. Enviou um pull request para o projeto.
2. Atualizadas as cores depois que o designer acertadamente percebeu as que eu escolhi (IANAD).
3. Atualizado as cores e atualizado o PR.
4. O PR foi então aceito e mesclado. Uhul!

Publicação do site:

1. Empurrado a primeira versão do site executando o script de publicação do Docusaurus na linha de comando:

   USE_SSH=true \  GIT_USER=caabernathy \  CURRENT_BRANCH=master \  yarn run publish-gh-pages

2. O CircleCI configurado usando as instruções fornecidas do Docusaurus. Havia 2 PRs para isso, o primeiropara a configuração inicial e o segundo para certificar-se de que o CircleCI só acionou para alterações no branch master (obrigado Joel Marcey!).

O site final foi publicado em https://facebookincubator.github.io/profilo/. Levara 1. horas para chegar ao estágio inicial do PR e mais meia hora aproximadamente para responder ao feedback de revisão e publicação do site.

Design

Veja como o site inicial pareceu quando a primeira pull request foi enviada:

A maioria das vezes na criação de conteúdo foi gasta escolhendo cores que funcionaram razoavelmente bem com o logotipo dado. Essas cores foram um bom ponto de salto para o feedback do designer. Eu usei o Photoshop para amostrar várias partes do logotipo.

Então peguei a representação RGB da cor e defini-a como a cor de base no Paletton. O site em seguida me deu várias opções de exibição de cores no site, editando o arquivo de configuração do site Docusaurus.

As cores primárias e secundárias selecionadas foram um bom ponto de salto para o feedback do designer.

Houve também modificações feitas no site padrão gerado pelo Docusaurus. Essas alterações foram feitas principalmente em torno da simplificação do rodapé e criação de uma página inicial personalizada para o Perfil que listou os recursos do projeto.

Veja como foi o site final:

Esta é uma página de exemplo mostrando o conteúdo principal, neste caso a página de introdução:

Isso também mostra a estrutura da barra lateral configurada através da edição de website/sidebars.json.

Por último, não tive que me preocupar em lidar com design responsivo. Você tira isso da caixa com o Docusaurus!

Considerações Finais

Os engenheiros Profilo ficaram felizes em ver que eles não precisavam alterar seu fluxo de trabalho para atualizar o conteúdo existente. Eles puderam continuar trabalhando com arquivos do Markdown. Isso continuará a ser verdade no futuro se novos documentos forem adicionados, embora possa haver algumas alterações de configuração necessárias se a navegação na barra lateral precisar ser atualizada.

A infraestrutura fornecida pelo Docusaurus facilitou a conversão de arquivos do Markdown em um site funcional. Embora o projeto tivesse apenas três documentos, isso deu um visual mais profissional ao Profilo. Portanto, valeu bem o pouco tempo de investimento para o fazer.