Hence Knowledge Repo
  • Home
  1. Tutorial
  2. Tutorial: como adicionar um documento ao Knowledge Repo
  • Processos
    • Gestão de Projetos
    • Padrões Hence
    • Ask Issues
    • Reproducible R scripts
    • Deploy e CI/CD
  • Credito / Modelagem
    • Crédito Imobiliário - Métricas de Perda
    • Modelo de Crédito Imobiliário (Quod)
    • Probabilidade de recuperação de crédito usando análise de sobrevivência
    • Tutorial Análise de sobrevivencia
    • Advanced Survival Modelling for Consumer Credit
    • IFRS 9 (Book: Tiziano Bellini)
  • Machine Learning / Engenharia
    • Feature Engineering (Max Kuhn)
    • Machine Learning Engineering
    • NLP
    • R Packages Development Guide
    • Functional Programming Workshop
  • Relatorios
    • Recuperação de crédito e Perda Esperada - Direcional Taxas
  • Teste
    • teste.html
    • teste2.html
  • Tutorial
    • Tutorial: como adicionar um documento ao Knowledge Repo

On this page

  • 1 Visão geral
  • 2 Pré-requisitos
  • 3 Estrutura do repositório
  • 4 Passo 1: criar o arquivo .qmd
  • 5 Passo 2: registrar no menu lateral
  • 6 Passo 3: commit e push
  • 7 Passo 4: acompanhar o pipeline
  • 8 Passo 5: conferir no site
  • 9 Casos especiais
    • 9.1 Notebooks com código R e dados externos
    • 9.2 Novos pacotes R
    • 9.3 Remover um documento
  • 10 Problemas comuns
  1. Tutorial
  2. Tutorial: como adicionar um documento ao Knowledge Repo

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:

  1. Criar o arquivo .qmd em src/notebooks/.
  2. Registrar o arquivo no menu lateral, dentro do _quarto.yml.
  3. Fazer commit e push das alterações.
  4. Acompanhar o pipeline de deploy no GitLab.
  5. 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-repo clonado 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.
Tip

Documentos escritos apenas em Markdown, sem blocos de código R, não exigem nenhuma configuração adicional.

5 Passo 2: registrar no menu lateral

Abra o _quarto.yml na raiz do repositório e localize o bloco website > sidebar > contents. Cada section é um grupo do menu (hoje existem Processos, Crédito / Modelagem, Machine Learning / Engenharia e Relatórios).

Para incluir o documento em um grupo existente, adicione uma linha em contents:

- section: "Crédito / Modelagem"
  contents:
    - src/notebooks/metricas-perda.qmd
    - src/notebooks/meu-documento.qmd

Para criar um grupo novo, adicione uma section com o mesmo nível de indentação das demais:

- section: "Teste"
  contents:
    - src/notebooks/teste.qmd
Warning

O YAML é sensível à indentação (2 espaços por nível). Um espaço a mais ou a menos faz o documento sumir do menu ou quebra a renderização do site.

Documentos em formato de apresentação (revealjs), como o effortless.qmd, são incompatíveis com o formato de website e ficam de fora do menu.

6 Passo 3: commit e push

Você pode usar o painel de controle de versão do editor ou o terminal.

Pelo editor:

  1. Abra o painel Source Control.
  2. Confira a lista de alterações. Deve aparecer o _quarto.yml (modificado) e o seu novo .qmd.
  3. Inclua os arquivos no stage, escreva a mensagem de commit e clique em Commit.
  4. 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 master

O 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.

  1. No GitLab, abra o projeto hence-sandbox/knowledge-repo.
  2. Vá em Build > Pipelines e abra o pipeline mais recente (o nome do commit aparece na listagem).
  3. Clique no job deploy para ver o log em tempo real.
  4. 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 master
Important

Se 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

  1. Apague o arquivo .qmd de src/notebooks/.
  2. Remova a linha correspondente (e a section, se ficar vazia) do _quarto.yml.
  3. 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