Syndication Links from State
Astro imports the syndication state file at build time and renders u-syndication links on every post, so the frontmatter never needs a second edit.
Reviewed by adrian
on
Microformats2 defines u-syndication, a link to the place where a post was copied to. When an article on my old site had a Bluesky copy, that link should appear on the article by itself. Editing frontmatter by hand after every deploy does not last past the second post. The syndication state file already held the answer, so the build reads it.
The setup
- Site: an Astro 6 static build, deployed by a shell script.
- Syndication state:
.bluesky-posted.jsonin the repository root, a map from canonical URL to Bluesky post URL (see Improving Bluesky Syndication). - Frontmatter: a
syndicationarray, only for targets added by hand (a newsletter, for example).
Why not the frontmatter
The obvious way is to write the Bluesky URL into the article after posting:
syndication:
- https://bsky.app/profile/adrian-altner.de/post/3mhqb4t6ceu2w
That needs a second commit after every syndication run: one to publish, one to add the URL. And the two places drift apart. Edit the article later and the syndication line is easy to forget.
Importing the state file
.bluesky-posted.json already holds the information and is committed after each run. Astro can import it at build time:
import bskyPosted from '../../../.bluesky-posted.json';
{
"https://adrian-altner.de/articles/2026/03/23/joining-the-indieweb/": "https://bsky.app/profile/adrian-altner.de/post/3mhqb4t6ceu2w"
}
Building the list of syndication URLs
The article page builds its canonical URL, looks it up and merges the result with the frontmatter entries:
const articleUrl = new URL(`/articles/${post.id}/`, Astro.site).toString();
const bskyPostUrl =
(bskyPosted as Record<string, string | null>)[articleUrl] ?? null;
const syndicationUrls: string[] = [
...(post.data.syndication ?? []),
...(bskyPostUrl ? [bskyPostUrl] : []),
];
post.data.syndication stays for URLs added by hand. The Bluesky URL is appended only when the state file has one. Notes use the same pattern with noteUrl.
Rendering the links
syndicationUrls drives the "Also on:" line below each post:
{
syndicationUrls.length > 0 && (
<p class="syndication-links">
Also on:{' '}
{syndicationUrls.map((url, i) => {
const host = new URL(url).hostname.replace('www.', '');
return (
<>
{i > 0 && ', '}
<a
class="u-syndication"
href={url}
rel="syndication noopener"
target="_blank"
>
{host}
</a>
</>
);
})}
</p>
)
}
The link text is the hostname, so Bluesky posts read bsky.app. A new target shows its own hostname without any change to the template.
Trailing slashes matter
webmention.io stores URLs exactly as they were sent. When Bridgy sends a webmention for an article URL with a trailing slash, the webmention component has to query with that same URL. Building the canonical URL with the slash in the template literal keeps it consistent:
const articleUrl = new URL(`/articles/${post.id}/`, Astro.site).toString();
// → "https://adrian-altner.de/articles/2025/12/01/hello-world/"
The keys in .bluesky-posted.json and the queries to webmention.io are then identical byte for byte. Without the slash, a lookup for /hello-world returns nothing even when mentions exist. That costs half an hour of debugging "broken webmentions".
The flow
Deploy, the script posts to Bluesky, the state file is updated, committed and pushed, the next build reads it, and the links appear on every page with a Bluesky post. The article frontmatter is touched once, when it is first published.
Takeaways
- Let the syndication state file be the source of truth. Frontmatter edits drift without anyone noticing.
- A JSON import in an Astro component costs nothing at runtime.
- One URL format with a trailing slash everywhere: in the lookup, in webmention.io and in the sitemap.
Based on
-
Syndication Links Without Frontmatter Editing
(
raw/2026/2026-03-23/syndication-links-without-frontmatter-editing.md) [post]
Topic
- IndieWeb Publishing on your own domain first and connecting personal websites with open standards such as Webmention and Microformats.
Builds on
- Improving Bluesky Syndication Notes as a second source, OG images compressed with Sharp below the blob limit, publish dates as timestamps and Bluesky URLs in a committed state file.
Uses
- Astro Tool for building websites from content such as Markdown. Ships plain HTML by default and only loads JavaScript where it is needed.
Mentioned in
- POSSE to Mastodon A Mastodon syndication script for articles and notes: state keyed by canonical URL, OG image uploads that fail open, backoff on 429, dry runs and batch limits.
- Troubleshooting Mastodon Backfeed A runbook for Mastodon, Bridgy and webmention.io: token scopes, deploy order, trailing slashes, 429s on media uploads and reactions that are gone upstream.
Mentioned
- Marking Up Posts with Microformats2 h-entry h-entry, h-card, h-feed and u-syndication classes on articles, notes and photos of an Astro site, machine-readable without any visible change.