Skip to content

fix: the blog index gets a Markdown twin and a CollectionPage like the changelog index - #277

Merged
sonpiaz merged 3 commits into
mainfrom
fix/blog-index-twin-admin
Nov 14, 2026
Merged

sonpiaz merged 3 commits into
mainfrom
fix/blog-index-twin-admin

Conversation

@sonpiaz

@sonpiaz sonpiaz commented Nov 13, 2026 •

Copy link
Copy Markdown
Member

What

The blog index gets a Markdown twin and structured data, like the changelog index. Every other public page already has both. The blog index answered Accept: text/markdown with HTML and carried no JSON-LD.

  • /blog.md: one line per post (date · category · linked title: description), newest first, then by slug.
    • It is prerendered and rewritten from /blog.md to /llms.md/blog.
    • It is dated by the newest post. That puts it in the sitemap with its .md, in llms-full.txt and in the twin list.
    • The middleware therefore answers Accept: text/markdown on /blog with it.
  • /blog: a text/markdown alternate link to /blog.md, and a CollectionPage whose ItemList is the twin's list, in the same order.
  • src/lib/blog.ts: one description and one order for the page, its JSON-LD and the twin. Posts of the same day now keep one stable order (by slug).
  • sitemap.ts: drops its separate blog index entry, which is now one of the pages.
  • src/generated/markdown-twins.json: regenerated by gen-llms. Besides /blog, it adds /changelog/improvements-2026-11-12, which the committed list had missed since that entry was published.

Note for maintainers: in a clean checkout, next build can fail to resolve @/../.source/server. fumadocs-mdx writes .source during the build, after Turbopack resolves imports. Running npx fumadocs-mdx first avoids it.

Tests first

  • T2 2eb153a (review round 1): the two host checks expected /blog to have no twin, so the hosted check went red once it got one. Both now expect it:
    • check-docs-host.mjs: /blog → /blog.md joins the negotiation pairs, /blog.md joins the not-a-page list, and the twin list must include /blog;
    • check-docs-host-http.mjs: the proxy serves /blog.md, and /blog answers the twin or HTML by Accept.
  • T d228475:
    • scripts/check-agent-surface.mjs treats /blog as a page with a twin: the expected /blog.md is rebuilt from the post sources, and the "blog index has no twin" exception is gone.
    • On the built /blog it checks one alternate link to /blog.md and one CollectionPage whose list matches the twin.
  • F f62d769.

Proof

Round 2, at head 2eb153a:

  • The updated check-docs-host.mjs run against the pre-change code fails on exactly the 10 /blog expectations: 9 negotiation lines over three hosts, plus the twin list.
  • At the head:
    • the docs build passes, and the twin list and llms.txt match the commit;
    • all three checks CI runs pass: check-agent-surface.mjs (201 PASS), check-docs-host.mjs and check-docs-host-http.mjs (through next start).

Round 1: both commits were built from a clean archive, with dependencies matching package-lock.json entry for entry and fumadocs-mdx run first.

  • At T: npm run build passes and check-agent-surface fails as intended ("Prerendered twin inventory differs from source": /llms.md/blog does not exist yet).
  • At F:
    • npm run build passes;
    • the regenerated markdown-twins.json and public/docs/llms.txt equal the committed ones;
    • check-agent-surface passes, 201 PASS lines, including PASS blog: twin, source body, sitemap dates, full corpus, twin link and CollectionPage.
  • The built /blog.md starts:
    ---
    id: "blog"
    type: "blog"
    url: "https://affitor.com/blog"
    updated: "2026-11-12"
    ---
    # Affitor Blog
    

Order

  1. The affitor.com proxy for /blog.md ships first, in the main site.
  2. Then a separate PR makes Vercel install from package-lock.json, which is what CI tests.
    • Today Vercel installs with yarn from a yarn.lock last updated in March, so deploys pick up newer dependencies than the tested ones.
    • The preview of this branch failed in that install step.
  3. This PR deploys after both.

🤖 Generated with Claude Code

sonpiaz and others added 2 commits November 13, 2026 06:34
…e changelog index

CORE-690 follow-up (13/11/2026 GEO scan: /blog fails G3 no twin, G5 no JSON-LD).
check-agent-surface now treats affitor.com/blog as a page with a twin:
- the inventory rebuilds /blog.md from the post sources: one line per post,
  newest first then by slug, dated by the newest post (no more "the blog
  index has no twin" exception in the sitemap inventory);
- the twin is prerendered, in the sitemap with its .md, in llms-full.txt and
  in markdown-twins.json, like every other twin;
- the built /blog page carries one text/markdown alternate link to /blog.md
  and one CollectionPage whose ItemList is the twin's list, in order.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…e changelog index

CORE-690 follow-up: the 13/11/2026 GEO scan found /blog with no Markdown twin
(G3) and no JSON-LD (G5); every other public page has both.
- src/lib/blog.ts: one description and one order for the index (newest first,
  then by slug, so same-day posts keep one order).
- /blog.md (agent-md blogIndex, prerendered, rewrite /blog.md -> /llms.md/blog):
  one line per post; the index is an agent page dated by the newest post, so
  it joins the sitemap with its .md, llms-full.txt and markdown-twins.json, and
  the middleware answers Accept: text/markdown on /blog with it.
- /blog: alternate link text/markdown -> /blog.md and a CollectionPage whose
  ItemList is the twin's list.
- sitemap.ts drops its separate blog index entry (now one of the pages).
- markdown-twins.json is the generator's own output. That also adds
  /changelog/improvements-2026-11-12, which main's committed list had missed
  since the changelog of 12/11 (the list was not regenerated then).
The description already carried an em dash on the live page; unchanged here.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@vercel

vercel Bot commented Nov 13, 2026 •

Copy link
Copy Markdown

The latest updates on your projects. Learn more about Vercel for GitHub.

Project Deployment Actions Updated
affitor-docs Ready Ready Preview Nov 13, 2026 3:06pm UTC

Request Review

Review r1 (H1): check-docs-host.mjs still listed /blog as a page without a twin
and asserted the twin list leaves it out, so the hosted check failed on every
host once the blog index got its twin. Both host checks now expect it:
- check-docs-host.mjs: /blog -> /blog.md joins the negotiation pairs, /blog.md
  joins the not-a-page list, and the twin list must include /blog.
- check-docs-host-http.mjs: the proxy host serves /blog.md as text/markdown, and
  /blog answers the twin for Accept: text/markdown and HTML otherwise, like
  /changelog (it was "no twin").

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sonpiaz
sonpiaz marked this pull request as ready for review November 14, 2026 00:31
@sonpiaz
sonpiaz merged commit 35f7cad into main Nov 14, 2026
5 checks passed

This branch was successfully deployed

1 active deployment
Preview — 2eb153a0 Deployed Nov 13, 2026 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant