Quartz

Resumo

Gerador de site estático “batteries-included” (em TypeScript) que transforma um vault Obsidian/Markdown em um site funcional. É a engine da wiki pública do DM Yan: wiki.yanbraga.com roda sobre Quartz a partir do conteúdo de content/.

Por que é relevante para Yan

• Publica para os jogadores a parte do vault que é pública (cenários, guias, perfis de NPCs player-safe) sem expor o prep do Mestre.
• Permite controlar visibilidade por pasta (ignorePatterns), rascunho (draft: true) e plugins customizados (RemoveSecrets).
• Repo atual usa Quartz v4.4.0 (a migração v5 foi interrompida pela metade e revertida).

Conceitos principais

• Build estático: npx quartz build processa o Markdown e gera a pasta public/ (HTML/CSS/JS) — sem backend.
• Config: quartz.config.ts (pageTitle, baseUrl, enableSPA, ignorePatterns) e quartz.layout.ts (layout/cabeçalho/rodapé).
• ignorePatterns: padrões de pasta/arquivo excluídos da publicação (ex.: **/2-Thylea/Personagens).
• RemoveDrafts: plugin oficial que remove notas com draft: true do build.
• Transformers/plugins: pipeline que converte callouts, wikilinks e componentes (SPA com popovers).
• SPA fallback: rotas inexistentes retornam o shell do site (HTTP 200 mesmo sem a página) — validação por conteúdo, não por status.

Como funciona

1. Conteúdo em content/ (Markdown + frontmatter) no repo Wiki-Yan.
2. npx quartz build gera o site em public/.
3. Deploy: container Docker quartz-wiki na VM (nginx servindo o build) — rebuild manual com docker compose build && docker compose up -d --force-recreate quartz-wiki.
4. DNS/HTTPS via Cloudflare Tunnel apontando para a porta interna do container.

Uso atual

• Repo: C:\Users\Yanbd\dev\Wiki-Yan (branch v4; remoto GitLab YBraga35/Wiki-Yan).
• Deploy: VM Oracle (hostname foundry), container quartz-wiki, rebuild via tar-pipe + docker compose.
• Segredos: política documentada em RPG/1-DM Toolkit/Guia Secrets da Wiki.md (callouts [!secret]/[!dm]/[!private] + ignorePatterns + drafts).
• Plugin custom RemoveSecrets em quartz/plugins/transformers/secrets.ts.

Decisões já tomadas

• Restaurar Quartz v4 após migração v5 incompleta que quebrava o build; backup reversível em .quartz-backup-v5/.
• Criar .dockerignore para reduzir o contexto de build (2.5GB → só o necessário).
• Defesa dupla de secrets: ignorePatterns + draft: true, porque seções de texto normal (ex.: “Informações Secretas”) não passam pelo RemoveSecrets (que só filtra callouts).

Limitações e cuidados

• Build local no Windows quebra com aliases contendo "?; " em notas antigas — buildar na VM.
• Syncthing da VM (pasta obs-sync-yan) esteve desatualizado — preferir tar-pipe/scp manual.
• Verificar publicação por CONTEÚDO do HTML baixado, não por código HTTP (SPA fallback retorna 200).

Questões em aberto

• Completar a migração para Quartz v5 (planejada, não priorizada).
• Automação de deploy via git (hoje o push não dispara rebuild).

Fontes

• Documentação oficial: https://quartz.jzhao.xyz (Confirmado)
• Repositório: https://github.com/jackyzha0/quartz (Confirmado)
• Uso local: evidência direta do repo Wiki-Yan e container quartz-wiki (Confirmado)