Sidecars instead of frontmatter

Where metadata for a markdown file lives. The markdown stays markdown. The file pair has a useful asymmetry: missing sidecar means draft, missing markdown means compilation error.

Where does metadata live alongside a markdown file? The dominant answer in static site generators is frontmatter: a YAML block at the top of the markdown file, delimited by ---. Jekyll does it, Hugo does it, Astro does it. Open any markdown file in those ecosystems and the first thing you see is structured config, not content.

The alternative is a sidecar: a separate .yml file beside the markdown. the-walk.md and the-walk.yml, side by side. The markdown holds content. The YAML holds metadata.

This is just separation of concerns at the file level. A markdown file with frontmatter is a hybrid: not pure markdown, and any tool that handles it has to know about the frontmatter convention or strip it. Sidecars keep the markdown clean. Open the file in any markdown editor and the first line of the file is the first line of the content.

The file pair also produces a useful asymmetry. A markdown file without a sidecar is a draft: invisible to the build. A sidecar without a markdown is a compilation error: the build expects content that isn't there. Drafts are silent. Broken pairs fail loudly.

A side benefit: Obsidian is my PKM system, and it stores its organizational metadata in frontmatter: tags, aliases, link relationships. Sidecars let the PKM framework and the site framework stay independent. build.rs reads the .yml for publication config and strips the .md of any Obsidian-style frontmatter before rendering. PKM stays in Obsidian. Publication config stays in the sidecar.

The cost is the file pair: two files instead of one, renames update both. Worth it. The markdown stays markdown.