0007: RSS feed and sitemap

Context#

People who should know about a decision rarely visit the archive; they live in feed readers, chat rooms and crawlers. An archive that can only be browsed is read by its authors. The site needs a standard way to push “a new record exists” and a standard way for crawlers and tools to discover every page, without a server to compute either.

Decision#

Every build writes an RSS 2.0 feed at /rss.xml with the newest records and a sitemap at /sitemap-index.xml. Both are linked from the <head> of every page so readers and crawlers discover them. Both need absolute URLs, which come from the url option.

How to use it#

Set the public URL#

1
export default defineConfig({
2
  url: 'https://decisions.acme.dev',
3
});

The feed#

/rss.xml holds the 50 newest records, in the same order as the index (by date, newest first). Each item:

The feed’s title is <title> – new records and its description is the site description. Only records (files inside a type folder such as adr/ or rfc/) are in the feed; guides and team intros are not.

Subscribe with any reader, or wire it to a chat room: most chat tools have an RSS integration that posts each new item to a channel. Because the items are sorted by date, a record whose date is changed to today appears as new.

The sitemap#

The sitemap is produced by Astro’s sitemap integration for every built page: records, pages, team pages, the index, timeline, backlog, authors and tags. It is written as sitemap-index.xml plus sitemap-0.xml (more parts for very large sites). Pages with draft: true are not built, so they are not listed. Point search engines at https://decisions.acme.dev/sitemap-index.xml, or let them find it through the <link rel="sitemap"> in the page head.

What is in <head>#

Every page carries:

1
<link rel="canonical" href="https://decisions.acme.dev/sre/adr/0007-define-slos/" />
2
<link rel="alternate" type="application/rss+xml" title="Acme Decisions – new records" href="/rss.xml" />
3
<link rel="sitemap" href="/sitemap-index.xml" />
4
<meta property="og:title" content="0007 Define SLOs per user journey · Acme Decisions" />
5
<meta property="og:url" content="https://decisions.acme.dev/sre/adr/0007-define-slos/" />

The paths include the base path when one is set. Extra head tags, for example a verification tag for a search console, go in the head option:

1
export default defineConfig({
2
  head: [{ tag: 'meta', attrs: { name: 'google-site-verification', content: 'abc123' } }],
3
});

Alongside the machine-readable files#

The feed is listed in the “For agents” section of the landing page together with llms.txt, llms-full.txt and decisions.json. Use the feed for “what changed”, decisions.json for “what is the full state”; see decisions.json.

Consequences#

• No server is involved: both files are rebuilt with the site, so they are exactly as fresh as the last deploy.
• The feed is driven by date, not by git history. A record with no date sorts last and never surfaces as new.
• The feed is capped at 50 items and has no per-project variant; filter in the reader by category (sre, rfc, a tag) when you need a slice.
• A wrong url silently produces a feed and sitemap full of unreachable links. Check dist/rss.xml once after the first build.
• There is no Atom or JSON Feed output.