marss

Markdown-changelog → RSS converter (benchristel), companion to mdsite.

Goals

Generate RSS from markdown without maintaining feed XML by hand. Used in the digital-garden pipeline: pnpm run build ran marss for the feed and mdsite for the HTML, with podcast.md producing both podcast.rss and a human-readable podcast.html from one source file.

Effectiveness

Adequate. The core loop is exactly right — one markdown file is the source of truth for both the human changelog and the machine feed — and the format is pleasant: feed metadata lives in an @marss HTML comment, and each dated H2 (## 2022-05-06: Title) becomes a feed item with its markdown body rendered to HTML in the description. For a podcast feed, though, it needed a post-processing script bolted on, and the tool is v0.0.1 with the maturity that implies.

What made it effective

• Single source of truth: the same changelog.md drives the RSS (via marss) and the HTML page (via mdsite). No drift between what readers and feed subscribers see.
• Zero-config invocation: npx marss changelog.md feed.rss. Metadata travels inside the document, not in a separate config.
• Item bodies are full markdown — styled text, links, images all render into the feed description.
• publishAtUtcHour handles date-only headings sensibly instead of emitting midnight timestamps.

Friction / pain points / surprises

No enclosure support. RSS podcast feeds require <enclosure> tags (audio URL, byte length, MIME type) per item; marss has no mechanism for them. The garden pipeline needed scripts/add-rss-enclosures.py run after every build to inject enclosures into marss's output — a mandatory, easy-to-forget second step that reintroduces exactly the hand-maintenance marss exists to remove. If your feed is a podcast, marss does half the job.

The counterfactual bit us on this very site (2026-07-29). Regular Reviews has a changelog page and an RSS feed — marss's textbook use case — but the changelog here is baked HTML (the markdown source was lost, see the mdsite review), so marss can't be dropped in. feed.xml is therefore edited by hand: bump lastBuildDate, escape entities, keep guids consistent, don't typo a pubDate. Every hand edit is a chance to emit invalid XML to subscribers. The fix is upstream: restore a markdown changelog as source of truth, then let marss own the feed.

v0.0.1 on npm. It works, but expect the ecosystem of one — same author as mdsite, same pre-release posture.