Move blog onto freeshard.net via Astro content collections (from docs MkDocs)

[ClaydeCode]

Summary

Move the blog from docs.freeshard.net/blog/ (MkDocs Material) onto the marketing site freeshard.net (Astro) using Astro content collections in landing-page/. The current split causes brand inconsistency (Material chrome on docs.* vs Astro look), splits SEO/link equity onto the docs subdomain, and contradicts the AI-company "agent opens PR with new content file" workflow already assumed for the Astro repo. Migration cost is low now — only a handful of posts exist.

Approach (Option A — Astro content collections)

src/content/blog/{en,de}/*.md(x) with typed frontmatter, dynamic routes for index + post pages, RSS via @astrojs/rss, OG image from frontmatter cover. One design system, one repo, one deploy pipeline. Astro ships RSS, sitemap, pagination, MDX, i18n routing — no new infra.

Rejected: headless CMS (overkill at single-author scale), Traefik reverse-proxy (still looks like MkDocs), iframe embed (bad SEO/a11y).

v1 scope (PR against landing-page/)

• src/content/config.ts — blog collection schema: title, description, pubDate, updatedDate?, cover (Astro image ref), lang (en|de), draft?, author. (No tags in v1 — see decisions.)
• src/content/blog/en/ and src/content/blog/de/ — content files, one MDX per post, cover colocated.
• Routes:
  • src/pages/[lang]/blog/index.astro — paginated list, newest first.
  • src/pages/[lang]/blog/[slug].astro — post page (cover, title, prose, related).
  • src/pages/[lang]/blog/rss.xml.ts — @astrojs/rss feed per language.
• OG image: post cover (1600×900) as-is.
• Header nav: language-aware "Blog" link.
• Sitemap: Astro integration picks up new routes once configured.

Estimated effort: 1–2 dev-days for v1 routing/styling, +~1h per post to migrate.

Decisions (resolved with Max)

• URL scheme: match existing /en/ /de/ style. Blog posts translated, with a disclaimer that translations are AI-generated. Translation automation deferred for now.
• Tags: defer — no tags in v1.
• Author byline: real authors (others may add posts too), not a single "Freeshard" voice. Schema carries an author field.
• Comments: none — read-only.
• Listing UX: standalone /blog/ page. A "Latest posts" strip on the landing-page home hero is a separate follow-up issue to tackle later.
• Drafts location: defer the KB-first vs repo-first decision until the agent-PR flow is real.

Migration of existing posts

1. Inventory posts at docs.freeshard.net/blog/ (small set — confirm before scoping).
2. Copy each into src/content/blog/<lang>/<slug>.mdx, adapt frontmatter.
3. Generate/reuse covers per visual-style spec.
4. 301 redirects docs.freeshard.net/blog/<old-slug>/ → freeshard.net/<lang>/blog/<slug>/ via Traefik redirectregex middleware on the docs router (same pattern as activate.freeshard.net).
5. Remove the blog/ plugin from MkDocs config once redirects are live.

Out of scope

• Moving non-blog docs (stay in MkDocs).
• Analytics setup (Plausible vs other) — separate decision.
• Keila newsletter integration — follow-up once v1 is live.
• "Latest posts" home-hero strip — separate follow-up issue.

Originated from KB research note 2026-05-28.