Tutorial: como adicionar um documento ao Knowledge Repo
Do arquivo .qmd até a publicação no site
1 Visão geral
Este tutorial mostra como publicar um novo documento no Hence Knowledge Repo (https://knowledge.hence-analytics.com). O processo tem cinco etapas:
- Criar o arquivo
.qmdemsrc/notebooks/. - Registrar o arquivo no menu lateral, dentro do
_quarto.yml. - Fazer commit e push das alterações.
- Acompanhar o pipeline de deploy no GitLab.
- Conferir o resultado no site.
O vídeo abaixo mostra o fluxo completo com um documento de teste. Cada etapa é detalhada nas seções seguintes.
2 Pré-requisitos
- Repositório
knowledge-repoclonado na sua máquina (GitLab:hence-sandbox/knowledge-repo). - Editor de código com terminal integrado (nas gravações, o Cursor).
- Permissão de escrita no repositório.
3 Estrutura do repositório
| Caminho | Para que serve |
|---|---|
src/notebooks/ |
Documentos do site (.qmd), imagens e dados de apoio |
_quarto.yml |
Configuração do site, incluindo o menu lateral |
index.qmd |
Página inicial |
_freeze/ |
Resultados de notebooks com R já executados (cache) |
install_packages.R |
Lista de pacotes R instalados no servidor |
.gitlab-ci.yml |
Definição do pipeline de deploy |
4 Passo 1: criar o arquivo .qmd
Dentro de src/notebooks/, crie um novo arquivo com extensão .qmd. Use letras minúsculas e hífen no nome, por exemplo meu-documento.qmd.
Todo documento começa com um cabeçalho YAML contendo o título, seguido do conteúdo em Markdown:
---
title: "Meu documento"
---
## Introdução
Texto do documento em Markdown.Documentos escritos apenas em Markdown, sem blocos de código R, não exigem nenhuma configuração adicional.
6 Passo 3: commit e push
Você pode usar o painel de controle de versão do editor ou o terminal.
Pelo editor:
- Abra o painel Source Control.
- Confira a lista de alterações. Deve aparecer o
_quarto.yml(modificado) e o seu novo.qmd. - Inclua os arquivos no stage, escreva a mensagem de commit e clique em Commit.
- Envie as alterações para o remoto (Sync Changes ou Push).
Pelo terminal:
git add _quarto.yml src/notebooks/meu-documento.qmd
git commit -m "feat: add meu-documento to website"
git push origin masterO histórico do projeto segue o padrão de prefixos nas mensagens: feat: para conteúdo novo, fix: para correções, docs: para documentação, ci: para o pipeline, chore: e refactor: para manutenção.
7 Passo 4: acompanhar o pipeline
O push dispara o pipeline de deploy automaticamente.
- No GitLab, abra o projeto
hence-sandbox/knowledge-repo. - Vá em Build > Pipelines e abra o pipeline mais recente (o nome do commit aparece na listagem).
- Clique no job deploy para ver o log em tempo real.
- Aguarde o status Passed. Nos testes gravados, o job levou cerca de 30 segundos.
O que o pipeline faz no servidor:
push -> GitLab CI -> SSH no servidor -> git pull -> quarto render -> nginx serve _site/
Em detalhes, ele puxa as mudanças com git pull, instala pacotes R novos caso o install_packages.R tenha mudado, gera o site com quarto render e reinicia o nginx.
Para o detalhamento completo de configuração (chave SSH, variáveis do GitLab, instalação de R e Quarto no servidor), consulte a página Deploy e CI/CD no menu Processos.
8 Passo 5: conferir no site
Com o pipeline concluído, acesse https://knowledge.hence-analytics.com.
- O novo grupo ou documento aparece no menu lateral.
- O endereço segue o padrão
https://knowledge.hence-analytics.com/src/notebooks/<nome-do-arquivo>.html. - A busca (ícone de lupa no topo) já encontra o novo conteúdo.
Se a página ainda não refletir a mudança, atualize o navegador ignorando o cache (Cmd + Shift + R no Mac, Ctrl + F5 no Windows).
9 Casos especiais
9.1 Notebooks com código R e dados externos
Notebooks que acessam dados externos (AWS, banco de dados, pacotes internos) não podem ser executados no servidor. Para esses casos, use o mecanismo de freeze do Quarto: você executa o documento localmente e o resultado é guardado em _freeze/.
# 1. Renderizar localmente, com acesso aos dados
quarto render src/notebooks/meu-arquivo.qmd
# 2. Commitar o cache gerado
git add _freeze/src/notebooks/meu-arquivo/
git commit -m "freeze: meu-arquivo"
git push origin masterSe o .qmd for editado sem atualizar o freeze, o pipeline tentará executar o R no servidor e falhará. Sempre atualize o freeze antes de subir alterações nesse tipo de notebook.
9.2 Novos pacotes R
Para usar um pacote R que ainda não está instalado no servidor, adicione o nome dele ao vetor pacotes em install_packages.R e faça o commit. O próximo pipeline detecta a mudança no arquivo e instala o pacote antes de renderizar o site.
9.3 Remover um documento
- Apague o arquivo
.qmddesrc/notebooks/. - Remova a linha correspondente (e a
section, se ficar vazia) do_quarto.yml. - Faça commit e push, como no Passo 3.
10 Problemas comuns
| Sintoma | Causa provável | O que fazer |
|---|---|---|
| Documento não aparece no menu | Arquivo não registrado no _quarto.yml ou indentação incorreta |
Revisar o bloco sidebar |
Pipeline falha no quarto render |
Erro no .qmd ou caminho errado no _quarto.yml |
Ler o log do job deploy e corrigir o apontado |
| Pipeline falha em notebook com R | Freeze desatualizado ou ausente | Renderizar localmente e commitar o _freeze/ |
| Página retorna 404 | Nome do arquivo ou caminho diferente do informado | Conferir o endereço src/notebooks/<nome>.html |
| Site não mudou após o deploy | Cache do navegador | Atualizar ignorando o cache |