Wtolotti's Notes

AGENTS

3 min read

Repository Guidelines

Estrutura do Projeto

  • content/: suas notas em Markdown e o conteúdo do site.
  • quartz/: código-fonte (CLI, build, componentes, plugins, estilos).
  • public/: saída de build; servido no preview local.
  • docs/: documentação do projeto (via npm run docs).
  • Configurações na raiz: quartz.config.ts, quartz.layout.ts, tsconfig.json.

Build, Testes e Desenvolvimento

  • npx quartz build --serve — compila e inicia servidor local com watch.
  • npx quartz build -o public — compila para public/ sem servir.
  • npm run docs — serve a documentação de docs/.
  • npm run check — type-check + verificação de formatação.
  • npm run format — formata com Prettier.
  • npm test — executa testes TypeScript via tsx.

Requisitos: node >=22 e npm >=10 (veja package.json#engines).

Estilo de Código

  • Prettier: largura 100, 2 espaços, sem ponto e vírgula, vírgulas finais.
  • Preferir TypeScript/TSX; módulos pequenos e focados.
  • Nomeação: componentes PascalCase em quartz/components/; utilitários camelCase em quartz/util/ (ex.: fileTrie.ts).

Diretrizes de Testes

  • Runner: tsx --test (via npm test).
  • Co-localize testes: *.test.ts(x) (ex.: quartz/util/path.test.ts).
  • Cubra parsers, processors e utilitários críticos.

Commits & Pull Requests

  • Commits curtos e no imperativo (ex.: “build: speed up esbuild cache”).
  • PRs com descrição clara, issues vinculadas e screenshots para mudanças visuais.
  • Rode npm run check e npm test antes de abrir PR.

Instruções para o Agente (Escritor de Blog)

  • Leia e edite apenas content/ (não altere quartz/ nem configs).
  • Escreva em Markdown com frontmatter YAML. Exemplo: 
    ---
title: Meu Post
tags: [blog, nota]
---
  • Links/embeds no estilo Obsidian: [[Nota]], ![[imagem.png]].
  • Anexos/imagens em content/__files/; referencie com ![[arquivo.ext]] ou ![alt](./__files/arquivo.ext).
  • Use content/templates/ se existir para padronizar novos posts.
  • Preview local: npx quartz build --serve -d content.

Padrões de Conteúdo (Quartz/Obsidian)

  • SEMPRE seguir a sintaxe e a documentação do Quartz/Obsidian para conteúdo.
  • Evite HTML cru (<div>, <img>, estilos inline). Prefira Markdown puro, títulos, listas, tabelas e callouts.
  • Callouts: use bloco com > [!info], > [!note], > [!warning], etc.
  • Imagens: prefira anexos locais em content/__files/ com ![[arquivo.png]]. Links externos são aceitos com ![Alt](https://...).
  • Links: use wikilinks [[Caminho/Nota]] entre páginas; mantenha títulos de seções estáveis para âncoras funcionarem.
  • Status/listas de tarefas: - [ ] e - [x] em vez de badges HTML.
  • Formatação responsiva fica a cargo do tema Quartz; não aplicar estilos inline.
  • Emojis: usar com moderação. Apenas em títulos/seções principais; evitar poluir listas e parágrafos. Mantenha âncoras estáveis (não troque emojis com frequência).
  • Tags e backlinks: use tags: no frontmatter e hashtags inline (#tag) quando ajudar na navegação. Conecte notas relevantes com wikilinks para construir um grafo útil de backlinks.

Graph View