astro-modular AGENTS.md

AGENTS.md — Astro Modular (Astro + Obsidian blog theme)

Source of truth for AI agents (Claude Code, Cursor, etc.) working in this repo. Read this entire file before making changes. It captures the things that are non-obvious about how Astro Modular is structured.

If the answer to "how does X work?" isn't here and it took you more than one round of investigation, add it here when you figure it out.

---

What Astro Modular is

Astro Modular is an Astro blog theme designed for Obsidian users, by David V. Kimball. The src/content/ folder is a real Obsidian vault — users write in Obsidian, commit, and publish.

Stack:

• Astro 7.x. Netlify / Vercel / GitHub Pages / Cloudflare Workers friendly.
• HTML comments cannot live inside a JSX expression. Astro 7's compiler rejects {cond ? ( followed by <!-- ... -->, and a {/* ... */} sibling next to an element in the same branch is equally invalid, because the branch must be a single expression. Put the comment INSIDE the element ({/* ... */} as a child) or ABOVE the whole expression (<!-- ... --> at template level). Astro 5 tolerated both.
• Obsidian vault as CMS. src/content/.obsidian/ is committed, with a curated plugin set.
• Swup for client-side page transitions (NOT Astro's ClientRouter).
• Tailwind + custom theme variables (17+ built-in color themes, switchable at runtime).
• Vanilla JS only — no React, no jQuery.
• Modular by design — almost every feature toggles via siteConfig in src/config.ts.

Core philosophy: Content lives in Obsidian. Standard markdown links, wikilinks, Obsidian embeds, callouts, and tags should work identically in Obsidian and on the live site. Don't take shortcuts that break Obsidian-native behavior.

---

Cardinal rules

1. NEVER edit files in src/content/ without explicit user permission. Posts, pages, projects, docs, frontmatter — all belong to the user. Only edit config, components, layouts, utilities, scripts, and plugins.
2. Use pnpm, not npm. Scripts: pnpm run <script>.
3. Use entry.id, NEVER entry.slug. slug is removed in Astro v6 and returns undefined. Folder-based entries have IDs like 'folder-name', NOT 'folder-name/index'.
4. Never disable the Astro dev toolbar (devToolbar.enabled: true in astro.config.mjs). The pnpm module-loading errors in the console are cosmetic.
5. Never disable vite.server.fs.strict. Security boundary.
6. Never use console.log() in production code. Use src/utils/logger.ts.
7. Never hardcode colors. Use Tailwind classes that reference theme variables (primary-*, highlight-*) with dark: variants. The theme system has 17+ color themes — hardcoded colors break all of them.
8. Never remove or rename // [CONFIG:KEY] comment markers in src/config.ts. The Astro Modular Settings Obsidian plugin uses them to edit config from inside the vault.
9. Never use destructive commands (rm -rf, git reset --hard, force push) without explicit approval. Investigate root causes.
10. Match existing patterns. This codebase already solves most problems consistently. Search before inventing.