📚 Guia de Módulos Externos no Quarto

Este guia explica como trabalhar com módulos externos (disciplinas) que ficam em pastas separadas do projeto principal e são sincronizados para este repositório.

🎯 Conceito

Um módulo externo é um projeto Quarto independente que pode: 1. ✅ Ser compilado e visualizado separadamente (na sua própria pasta externa) 2. ✅ Ser integrado ao site principal (alessiojr.com) via sincronização de conteúdo

Diferente da abordagem com links simbólicos, agora usamos um script de sincronização que copia fisicamente os arquivos necessários. Isso garante melhor compatibilidade com Git, CI/CD e visualização em diferentes ambientes.

📁 Estrutura

/mnt/arquivos/GDrive/Documents/Disciplinas/
└── clp/                          # Pasta fonte externa (Master)
    ├── _quarto.yml               # Configuração local
    ├── index.qmd                 # Conteúdo
    └── ...

/dados/projetos/sites/alessiojr.com/
├── disciplines/                  # Conteúdo sincronizado (Cópia)
│   └── clp/                      # Arquivos copiados da fonte
└── scripts/
    └── sync-modules.sh           # Script que realiza a sincronização

🚀 Como Usar

1️⃣ Trabalhar na Pasta Fonte (Independente)

Você deve continuar editando seus arquivos diretamente na pasta do Google Drive:

Preview Local do Módulo

cd /mnt/arquivos/GDrive/Documents/Disciplinas/clp
quarto preview

2️⃣ Integrar e Sincronizar no Site Principal

Quando quiser que as alterações apareçam no site principal:

Passo A: Sincronizar

Execute o script de sincronização na raiz do projeto principal:

cd /dados/projetos/sites/alessiojr.com
./scripts/sync-modules.sh

Este script irá: 1. Ler a configuração de módulos. 2. Limpar as pastas em disciplines/. 3. Copiar os arquivos .qmd, PDFs, imagens e diretórios de conteúdo da fonte para o destino.

Passo B: Renderizar o Site Principal

quarto render
# ou use o preview para ver as mudanças em tempo real
quarto preview

📝 Criar um Novo Módulo Externo

Passo 1: Criar a estrutura na pasta externa

Crie sua disciplina normalmente em sua pasta de preferência (ex: no GDrive).

Passo 2: Registrar o módulo no site principal

Edite o arquivo scripts/sync-modules.sh e adicione seu novo módulo ao array MODULES:

MODULES=(
    "clp|/caminho/para/clp"
    "nova-disciplina|/caminho/para/nova-disciplina"
)

Passo 3: Executar a sincronização

./scripts/sync-modules.sh

Passo 4: Adicionar ao Navegador (Opcional)

Edite o _quarto.yml do site principal para adicionar a nova disciplina ao menu navbar.

🔧 Workflow de Manutenção

[!IMPORTANT] Sempre edite na pasta fonte. As pastas dentro de disciplines/ no projeto principal são temporárias e serão sobrescritas a cada execução do sync-modules.sh.

  1. Faça suas alterações na pasta do GDrive.
  2. Valide com quarto preview dentro da pasta da disciplina.
  3. Volte ao projeto alessiojr.com e rode ./scripts/sync-modules.sh.
  4. Faça o commit das alterações sincronizadas (se desejar versionar o conteúdo).

⚠️ Considerações Importantes

  1. Git e CI/CD: Como os arquivos são copiados fisicamente, o Git agora enxerga o conteúdo real. Isso facilita o deploy automatizado (GitLab/GitHub Actions) pois não há dependência de caminhos absolutos locais ou links simbólicos.
  2. Filtros Lua: O site principal usa o filtro scripts/release-links.lua que corrige automaticamente os caminhos dos links sincronizados para que funcionem corretamente dentro da estrutura do site principal.
  3. Backup: O conteúdo original permanece seguro no seu GDrive.

📚 Exemplo Completo: sync-modules.sh

O script foi desenhado para ser inteligente e ignorar arquivos de configuração específicos da disciplina (como _quarto.yml local) para não conflitar com as configurações globais do site principal.

# O script copia:
# - Todos os .qmd da raiz da disciplina
# - Pastas: conteudo, avaliacoes, trabalho, planodeensino, etc.
# - Arquivos de suporte: .pdf, .md, .bib, .png, .jpg, etc.

🆘 Troubleshooting

Alterações não aparecem no preview do site principal

  1. Verifique se você salvou o arquivo na pasta fonte (GDrive).
  2. Verifique se executou o ./scripts/sync-modules.sh.
  3. Se o quarto preview estiver rodando, ele deve detectar a mudança de arquivos em disciplines/ e atualizar automaticamente.

Erro de “Pasta fonte não encontrada”

Verifique se o caminho no scripts/sync-modules.sh está correto e se o GDrive está montado no seu sistema.

Back to top