Como atualizar o manual de estilo?

O site do manual de estilo é construído utilizando o MkDocs, uma ferramenta que transforma arquivos de texto simples (Markdown) em sites de documentação.

Acesso ao Github e configuração do repositório do Website

Para visualizar o repositório do manual de estilo, é preciso que um adminsitrador da reunião no github libere o acesso. Além disso, será preciso que o repositório tenha sido configurado no seu computador. Caso ainda não esteja, veja a seção de contribuição para fazer o setup.

Entendendo o MkDocs

O MkDocs é um gerador de sites estáticos, especializado em criar sites de documentação a partir de arquivos de texto simples. Pense nele como uma linha de montagem: você fornece a matéria-prima (o conteúdo) e as instruções (a configuração), e ele entrega o produto final (o site).

Seu funcionamento se baseia em três pilares:

1. Arquivos de Conteúdo (Markdown): Todo o conteúdo que você lê no manual de estilo é escrito em arquivos de texto com a extensão .md. Esses arquivos usam uma linguagem de formatação simples chamada Markdown, que permite criar títulos, listas, links e inserir imagens de forma intuitiva, sem precisar saber HTML. Todos esses arquivos ficam na pasta site-governanca/docs/.

2. Arquivo de Configuração (mkdocs.yml): Este é o arquivo principal que organiza todo o site. Nele, definimos:

   • O título do site.
   • O menu de navegação: a ordem e a estrutura das páginas.
   • O tema visual: a aparência, as cores e o layout do site.
   • Plugins e extensões que adicionam funcionalidades, como buscas ou abas.

3. Processo de Construção: Quando a automação é acionada, ela executa um comando que faz o MkDocs ler o arquivo de configuração (mkdocs.yml), processar todos os arquivos Markdown, e gerar uma versão em HTML de cada página. O resultado é um site completo, rápido e seguro, que é então enviado para o servidor.

O processo de atualização no website

O repositório do site de governança foi configurado com uma automação para atualizar o site. Quando um Pull Request é mergeado na branch main, um script de atualização é iniciado pelo github e o website será atualizado no site do Manual de Estilo.

Abaixo, o processo de atualização é explicado com mais detalhes:

Automação (GitHub Actions): Assim que sua proposta é aprovada e incorporada à ramificação principal (main), o nosso robô (o GitHub Actions) entra em ação.

O que o robô faz a partir daí?

• Preparação do Ambiente: Ele prepara um ambiente limpo com todas as ferramentas para construir o site.
• Construção do Site: Transforma todos os arquivos de texto (Markdown) em um site navegável (HTML).
• Publicação no Servidor: Conecta-se de forma segura ao servidor e publica a nova versão do site, substituindo a antiga.

Esse fluxo garante que o site seja atualizado apenas com conteúdo revisado e aprovado.