Pular para o conteúdo principal

📖 Manual de Instalação e Uso do Docusaurus

Este manual tem como objetivo guiar você no processo de instalação das ferramentas necessárias, configuração do ambiente e fluxo de trabalho para contribuir com a documentação em Docusaurus. Seguindo estas etapas e boas práticas, garantiremos uma experiência de desenvolvimento fluida e colaborativa.

1. Primeiros Passos no GitHub​

O GitHub é a plataforma onde nosso projeto Docusaurus está hospedado. É fundamental ter acesso e familiaridade com ele.

1.1. Criação de Conta no GitHub​

  1. Acesse o site do GitHub: github.com.
  2. Crie sua conta.
    • Recomendação: Utilize seu e-mail institucional (@saude.pe.gov.br) para facilitar a identificação e o gerenciamento de permissões dentro da organização.

1.2. Acesso ao Projeto​

  1. Após criar sua conta, solicite à gestão que o projeto Docusaurus seja compartilhado com sua conta GitHub.
  2. Ao receber o acesso compartilhado, sugerimos favoritar o projeto (clicando na estrela ⭐️ na página do repositório) para melhor visualização e acesso rápido.

2. Download e Instalação de Ferramentas Essenciais​

Para trabalhar com o Docusaurus, você precisará de algumas ferramentas no seu computador

Siga os links abaixo para o download:

2.1. Procedimento para Profissionais Qintess (Opcional)​

Se você é um profissional da Qintess e possui restrições de instalação, siga este procedimento:
  1. Acesse a ferramenta de abertura de chamados: centraldeservicos.qintess.com.
  2. Navegue até: SERVIÇOS DE TECNOLOGIA >> APLICATIVOS >> OUTROS >> INSTALAR.
  3. Importante: Ao abrir o chamado, informe que você já realizou o download dos aplicativos. Recomenda-se abrir um chamado para cada aplicativo (Node.js, VS Code, Git) para melhor acompanhamento.

3. Configuração do Ambiente no VS Code​

Extensões Recomendadas para VS Code

Para otimizar sua experiência de desenvolvimento no VS Code, sugerimos a instalação das seguintes extensões.

Como instalar extensões no VS Code:

  1. Abra o VS Code.
  2. No menu lateral esquerdo, clique no ícone Extensões (geralmente o quarto ou quinto ícone de cima para baixo, que parece um quadrado com outro quadrado flutuando ao lado 📦).
  3. Na barra de pesquisa que aparecer, digite o nome da extensão (ex: npm Intellisense).
  4. Clique em Instalar ao lado da extensão desejada.

Lista de Extensões Recomendadas:

  • npm Intellisense (Christian Kohler)
  • GitLens — Git supercharged (GitKraken)
  • IntelliCode (Microsoft)
  • IntelliCode API Usage Examples (Microsoft)
  • Live Server (Ritwick Dey)
  • Markdown All in One (Yu Zhang)
  • Markdown Preview Enhanced (Yiyi Wang)
  • markdownlint (David Anson)
  • Path Intellisense (Christian Kohler)
  • Prettier - Code formatter (Prettier)
  • yarn (Gamunu Balagalla)

Após instalar as ferramentas, vamos configurar o VS Code para começar a trabalhar.

  1. Abra o VS Code.
  2. Abra um novo terminal (o terminal utilizado normalmente é o gitbash) integrado no VS Code (você pode ir em Terminal > New Terminal).

Se encontrar dificuldades durante a execução, veja o vídeo de demonstração

3.1. Instalar Yarn Globalmente​

O Yarn é um gerenciador de pacotes que o Docusaurus utiliza.

npm install -g yarn

3.2. Verificar Versões​

Verifique se o npm e o Yarn foram instalados corretamente:

npm -v
yarn -v

3.3. Configurar Git​

Configure seu nome e e-mail no Git. Essas informações serão usadas para identificar suas contribuições (commits).

git config --global user.name "Seu Nome ou Usuário"
git config --global user.email "seu.email@exemplo.com"
  • Dica: Use o mesmo nome e e-mail que você utilizou no GitHub para manter a consistência.

4. Clonando e Iniciando o Projetos​

Agora que seu ambiente está configurado, vamos trazer o projeto Docusaurus para sua máquina.

4.1. Clonar o Repositório​

  1. No VS Code, pressione Ctrl + Shift + P para abrir a Paleta de Comandos.
  2. Digite git:Clone e selecione a opção.
  3. Escolha Clone from GitHub.
  4. Selecione o projeto Docusaurus na lista.
  5. Escolha ou crie uma pasta local onde você deseja clonar o projeto.

4.2. Instalar Dependências​

Navegue até a pasta do projeto clonado no terminal do VS Code e instale todas as dependências necessárias:

yarn

4.3. Iniciar a Aplicação​

Após a instalação das dependências, você pode iniciar o Docusaurus em modo de desenvolvimento. Isso permitirá que você veja suas alterações em tempo real no navegador.

yarn start
  • O Docusaurus geralmente abrirá uma nova aba no seu navegador com o projeto rodando.

5. Boas Práticas para Edições​

Antes de começar a editar, siga estas boas práticas para evitar conflitos e facilitar a colaboração.

5.1. Criar uma Nova Branch​

Recomendamos fortemente que você crie uma nova branch a partir da main antes de iniciar quaisquer edições. Isso isola suas alterações e evita conflitos com o trabalho de outras pessoas.

  • No VS Code, você pode clicar no nome da branch na barra de status inferior (geralmente main) e selecionar Create new branch.
  • Ou no terminal: 
    git checkout main
    git pull origin main # Garanta que sua branch main está atualizada
    git checkout -b nome-da-sua-feature

Se encontrar dificuldades durante a execução, veja o vídeo de demonstração

5.2. Convenção de Nomenclatura de Branches​

Ao nomear sua branch, siga estas recomendações para manter a organização:​

  • ❌ NÃO UTILIZE: Espaços, caracteres especiais, números ou letras maiúsculas.

  • ✅ UTILIZE: Apenas letras minúsculas, hífens (-) para separar palavras.

    • Exemplos: docs/instalacao-docusaurus, fix/erro-link, feature/nova-pagina-contato.

6. Subindo Alterações para o GitHub​

Após finalizar suas atualizações, é hora de enviá-las para o GitHub.

6.1. Commit e Push via VS Code​

  1. No VS Code, pressione Ctrl + Shift + P para abrir a Paleta de Comandos.

  2. Digite git:Push e selecione a opção. O VS Code fará o commit das suas alterações (se houver) e as enviará para a sua branch remota.

    ---OU---

  3. Acesse o menu Source Control (Controle de Código-Fonte) no menu lateral do VS Code (normalmente o terceiro ícone).

  4. No painel "Source Control", você verá as alterações nos arquivos. Adicione uma mensagem de commit clara e concisa que descreva suas alterações.

  5. Clique em "Commit" (o botão com o símbolo de ✔️).

  6. Após o commit, clique em "Publish Branch" (se for a primeira vez que você envia essa branch) ou "Sync Changes" (se você já publicou a branch e está apenas sincronizando).

Se encontrar dificuldades durante a execução, veja o vídeo de demonstração

6.2. Abrindo um Pull Request no GitHub​

Após suas alterações estarem no GitHub (na sua branch), você precisará criar um Pull Request (PR) para que elas sejam revisadas e integradas à branch principal (main).

  1. Acesse o projeto no GitHub pelo navegador.
  2. Vá para a aba "Branches".
  3. O GitHub geralmente mostrará um banner indicando que sua branch tem alterações e oferecerá um botão "Compare & pull request". Clique nele.

4. Na página de criação do Pull Request:​

  • Verifique se a branch base é main e a branch de comparação é a sua.

    • Dê um título claro e uma descrição detalhada para o PR, explicando o que foi alterado e porquê.
    • Adicione revisores, se necessário.

  • Clique em "Create pull request".

Se encontrar dificuldades durante a execução, veja o vídeo de demonstração

6.3. Solicitação de Deploy/Aprovação​

Para que suas atualizações reflitam no servidor (ambiente de produção), será necessário solicitar o "Deploy/Aprovação" para a gestão após o seu Pull Request ser aprovado e mesclado à branch main.

7. Realizando Novas Alterações (Atualizações)​

Sempre que for iniciar um novo ciclo de edições no projeto, siga este fluxo:​

  • Garanta que sua branch main local esteja atualizada com as últimas alterações do repositório remoto.
  • No VS Code, pressione Ctrl + Shift + P.
  • Digite git: Pull from.
  • Selecione origin/main.
  • Ou no terminal: 
    git checkout main
    git pull origin main

Se encontrar dificuldades durante a execução, veja o vídeo de demonstração

  1. Crie uma nova branch a partir da sua main atualizada conforme a Seção 5.1.
  2. Realize suas edições.
  3. Siga os mesmos passos da Seção 6 para commitar, enviar e abrir um Pull Request.