Auto-generate index.md from x/quartz-homepage.md at build time

Context and Problem Statement

index.md at vault root served only the Quartz public site (homepage). It was visually noisy in the Obsidian vault sidebar — a public-facing artifact mixed with vault-internal content.

Considered Options

• Move homepage content to x/quartz-homepage.md; auto-generate index.md at build time; gitignore index.md locally.
• Use a Quartz CLI flag for custom homepage path.
• Symlink index.md → x/quartz-homepage.md.
• Keep index.md at root and accept the visual noise.

Decision Outcome

Chosen option: “Move to x/quartz-homepage.md + auto-generate at build time”, because vault-side cleanliness (one fewer top-level file) without sacrificing the public homepage. Build-time generation is the standard pattern for derived artifacts.

Implementation:

• Homepage content lives in x/quartz-homepage.md (vault-internal, editable like any markdown note).
• /index.md added to .gitignore so it never appears at vault root locally.
• Workflow step (.github/workflows/deploy.yml) copies x/quartz-homepage.md → index.md before npx quartz build.
• Workflow path triggers updated to include x/quartz-homepage.md; keep x/templates/, x/attachments/ excluded.

Pros and Cons of the Options

Auto-generate at build time

• Good, because clean vault sidebar.
• Good, because standard pattern for derived artifacts.

Quartz CLI flag for custom homepage

• Bad, because no such flag exists; Quartz expects index.md at content root.

Symlink

• Bad, because iCloud Drive has historical reliability issues with symlinks.

Keep index.md at root

• Bad, because visual noise in Obsidian sidebar; auto-generation is one workflow line.