Guia rápido
Este guia vai orientá-lo no processo de criação, configuração e publicação do seu portal de documentação utilizando o Docusaurus. Antes de continuar, acreditamos que seja importante você ter conhecimento sobre Git, Markdown, Javascript e CSS básico. Sugerimos que você faça o nosso tutorial de Git.
Este artigo tem como objetivo guiá-lo pelas etapas fundamentais para criar o portal de documentação. Se o portal já estiver configurado, concentre-se apenas em manter as documentações atualizadas durante o desenvolvimento.
Pré requisitos
| Recurso/Programa |
|---|
| Node 20.14 ou superior |
| Visual Studio Code |
| Git |
| Extensão Markdown Snippets for MDX and Docusaurus para o VS Code |
Clone do repositório
Abaixo estão os repositórios disponíveis para os portais de documentação de cada produto. Caso o repositório do seu produto não esteja listado, solicite a criação aqui.
| Produto | Repositório |
|---|---|
| NDD Elog | Acessar |
| NDD Orbix | Acessar |
| NDD Frete | Acessar |
| NDD Cargo | Acessar |
| NDD Move | Acessar |
- Acesse o link do repositório
- Clique em Clone e copie a URL
- Na sua máquina, abra o cmd
- Navegue até a pasta que deseja clonar o repositório e execute o comando
git clone <URL_DO_REPOSITORIO>
Recomendamos que você não realize o clone dentro de alguma pasta que esteja sendo sincronizada pelo OneDrive.
Criar uma nova branch
Com o projeto aberto no VS Code, vamos criar uma nova branch para realizar a configuração inicial.
- No VS Code, abra o terminal
ctrl|cmd + ' - Execute o comando
git branch feature/configuracao-inicial
- Agora execute o comando
git checkout feature/configuracao-inicial
- Publique a branch com o comando
git push origin feature/configuracao-inicial
Instalar as dependências
- Ainda no terminal do VS Code
- Execute o comando
npm install - Aguarde o assistente finalizar
Configuração básica
- Abra o arquivo
custom-config.json - altere as seguintes informações:
- title: Insira o título para o seu portal, este conteúdo ficará disponível na página inicial
- tagline: Insira o subtítulo ou chamada para o meu produto, este conteúdo ficará disponível na página inicial
- buttonText: Texto que você deseja mostrar no botão
- vertical: Vertical que o produto pertence,
dispositivos,logisticaoufiscal
- Salve o arquivo
Testar o portal
Ao finalizar as configurações, vamos testar o portal localmente.
- Abra o terminal
ctrl|cmd + ' - Execute o comando
npm run build - Após a finalização, execute o comando
npm run serve
Você pode parar a execução do portal clicando ctrl + C.
Publicar o portal
Chegamos a última etapa do nosso guia rápido, vamos publicar o portal de documentação.
Enviar as alterações
Primeiro vamos enviar as alterações para o repositório remoto.
- Abra o terminal
ctrl|cmd + ' - Execute o comando
git add .
- Agora execute o comando
git commit -m "Configuração inicial"
- Por fim execute o comando
git push origin feature/configuracao-inicial
Criar a Pull request
- Acesse o repositório
- Você deve estar vendo uma mensagem semelhante a You updated feature/configuracao-inicial 1m ago
- Clique em Create a pull request
Informações que devem estar selecionadas:
- O repositório do seu portal
- A branch criada aqui
- Novamente o repositório do seu portal
- A Branch main
- Termine de preencher a Pull request e clique em Create
- Clique em Aprove e depois em Complete
- Selecione Complete associated work items after merging para finalizar quaisquer work itens linkados
- Selecione Delete
feature/configuracao-inicialafter merging para deletar a branch que está sendo unificada
- Clique em Complete merge
Acesse a documentação oficial da Microsoft para saber mais sobre Pull requests.
Verificar a publicação
- No TFS acesse Pipelines 🚀
- Selecione o Pipeline do seu produto
- Clique sobre o Stage que está em execução 🔄
- Clique sobre Deploy da aplicação no SWA
- Aqui você poderá observar as etapas da publicação
Continuar evoluindo o portal de documentação
Suporte
Qualquer necessidade você pode contar conosco, entre em contato pelo teams ou e-mail: paulo.henrique@ndd.tech.