From d228475aa912723113af2194238b59c7a8ec8ea9 Mon Sep 17 00:00:00 2001 From: sonpiaz Date: Fri, 13 Nov 2026 06:34:14 -0800 Subject: [PATCH 1/3] test: the blog index has a Markdown twin and a CollectionPage like the 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 --- scripts/check-agent-surface.mjs | 50 ++++++++++++++++++++++++++++++--- 1 file changed, 46 insertions(+), 4 deletions(-) diff --git a/scripts/check-agent-surface.mjs b/scripts/check-agent-surface.mjs index 877cd66..25cbee6 100644 --- a/scripts/check-agent-surface.mjs +++ b/scripts/check-agent-surface.mjs @@ -205,9 +205,50 @@ function inventory() { updated: data.updated ?? data.date, sourceDate: data.updated ?? data.date, body: markdown(data, id), + date: data.date, category: data.category, title: data.title, description: data.description, }; }); - return [...docs, ...posts, ...changelogInventory()]; + return [...docs, blogIndexInventory(posts), ...posts, ...changelogInventory()]; +} + +// Mirror of BLOG_DESCRIPTION in src/lib/blog.ts. +const BLOG_DESCRIPTION = 'Essays, launches, and guides from the team building Affitor — affiliate infrastructure for the agent era.'; + +/** + * affitor.com/blog and its twin /blog.md (CORE-690 follow-up, 13/11/2026): one line per post, newest first and then + * by slug, so same-day posts keep one order on the page, in its JSON-LD and in the twin. Dated by the newest post. + * Mirror of blogIndex() and sortedPosts() in src/lib/blog.ts and src/lib/agent-md.ts. + */ +function blogIndexInventory(posts) { + const listed = [...posts].sort((a, b) => b.date.localeCompare(a.date) || a.id.localeCompare(b.id)); + const updated = posts.map((post) => post.updated).sort().at(-1); + const lines = listed.map((post) => `- ${post.date} · ${post.category} · [${post.title}](${post.url}): ${post.description}`); + return { + id: 'blog', type: 'blog', url: `${ORIGIN}/blog`, updated, sourceDate: updated, listed, + body: `# Affitor Blog\n\n> ${BLOG_DESCRIPTION}\n\n## Posts\n\n${lines.join('\n')}\n`, + }; +} + +/** The built /blog page: the twin link, and one CollectionPage whose ItemList is the twin's list, in order. */ +function checkBlogIndexHtml(index) { + const html = read(join(APP, 'blog.html')); + const links = [...html.matchAll(/]*>/g)].map((match) => match[0]) + .filter((tag) => /\brel="alternate"/.test(tag) && /\btype="text\/markdown"/.test(tag)); + assert.equal(links.length, 1, '/blog: expected one text/markdown alternate link'); + assert.equal(new URL(decodeEntities(links[0].match(/\bhref="([^"]*)"/)[1]), ORIGIN).href, `${ORIGIN}/blog.md`, '/blog: twin link'); + const schemas = [...html.matchAll(/]*\btype="application\/ld\+json"[^>]*>([\s\S]*?)<\/script>/g)] + .map((match) => JSON.parse(match[1])).filter((schema) => schema['@type'] === 'CollectionPage'); + assert.equal(schemas.length, 1, '/blog: expected one CollectionPage'); + const [schema] = schemas; + assert.equal(schema['@id'], index.url, '/blog: CollectionPage @id'); + assert.equal(schema.description, BLOG_DESCRIPTION, '/blog: CollectionPage description'); + assert.equal(schema.mainEntity?.['@type'], 'ItemList', '/blog: CollectionPage mainEntity'); + assert.equal(schema.mainEntity.numberOfItems, index.listed.length, '/blog: ItemList size'); + assert.deepEqual( + schema.mainEntity.itemListElement.map((item) => [item.position, item.url, item.name]), + index.listed.map((post, i) => [i + 1, post.url, post.title]), + '/blog: ItemList differs from the twin list', + ); } /** @@ -549,8 +590,8 @@ function main() { }; }); const expectedUrls = pages.flatMap((page) => [page.url, markdownUrl(page)]); - // The blog index has no twin; it is listed once, dated by the newest post (CORE-690). - expectedUrls.push(`${ORIGIN}/blog`, `${SITE}/llms.txt`, `${SITE}/llms-full.txt`); + // The blog index is a page with a twin since 13/11/2026 (CORE-690 follow-up), dated by the newest post. + expectedUrls.push(`${SITE}/llms.txt`, `${SITE}/llms-full.txt`); assert.deepEqual(entries.map((entry) => entry.url).sort(), expectedUrls.sort(), 'Sitemap URL inventory differs from source'); const dates = new Map(entries.map((entry) => [entry.url, entry.lastmod])); const datedPages = pages.filter((page) => page.updated); @@ -599,7 +640,8 @@ function main() { assert.equal(corpus.indexOf(twin, position + twin.length), -1, `${page.id}: duplicate twin in llms-full.txt`); corpus = corpus.slice(0, position) + corpus.slice(position + twin.length); if (page.type === 'doc') checkHtml(page, new URL(page.url).pathname); - console.log(`PASS ${page.id}: twin, source body, sitemap dates, full corpus${page.type === 'doc' ? ', HTML and canonical' : ''}`); + if (page.id === 'blog') checkBlogIndexHtml(page); + console.log(`PASS ${page.id}: twin, source body, sitemap dates, full corpus${page.type === 'doc' ? ', HTML and canonical' : page.id === 'blog' ? ', twin link and CollectionPage' : ''}`); } assert.match(corpus, /^\n*$/, 'llms-full.txt contains unexpected content or extra pages'); From f62d76986ab7aec6def4b8bfbd47b76b8befbb42 Mon Sep 17 00:00:00 2001 From: sonpiaz Date: Fri, 13 Nov 2026 06:47:55 -0800 Subject: [PATCH 2/3] fix: the blog index gets a Markdown twin and a CollectionPage like the 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 --- next.config.mjs | 2 ++ scripts/gen-llms.js | 6 ++-- src/app/blog/page.tsx | 41 ++++++++++++++++++++-------- src/app/llms.md/[[...slug]]/route.ts | 1 + src/app/sitemap.ts | 6 ++-- src/generated/markdown-twins.json | 2 ++ src/lib/agent-md.ts | 22 ++++++++++++++- src/lib/blog.ts | 16 +++++++++++ 8 files changed, 78 insertions(+), 18 deletions(-) create mode 100644 src/lib/blog.ts diff --git a/next.config.mjs b/next.config.mjs index b1afe62..7557be4 100644 --- a/next.config.mjs +++ b/next.config.mjs @@ -33,6 +33,8 @@ const config = { source: '/blog/:path*.md', destination: '/llms.md/blog/:path*', }, + // The blog index twin (CORE-690 follow-up, 13/11/2026). + { source: '/blog.md', destination: '/llms.md/blog' }, // affitor.com/changelog (14/10/2026): the index twin and one twin per entry. { source: '/changelog.md', destination: '/llms.md/changelog' }, { source: '/changelog/:slug.md', destination: '/llms.md/changelog/:slug' }, diff --git a/scripts/gen-llms.js b/scripts/gen-llms.js index 500bb28..bd7d3fc 100644 --- a/scripts/gen-llms.js +++ b/scripts/gen-llms.js @@ -99,12 +99,14 @@ ${sections()} const mdxSlugs = (dir) => readdirSync(join(ROOT, dir)).filter((file) => file.endsWith('.mdx')).map((file) => file.slice(0, -4)); /** - * Page paths with a real .md twin (src/app/llms.md): docs pages, blog posts (content/blog), the - * changelog index and its entries (content/changelog/*.mdx). Sorted, so the file is deterministic. + * Page paths with a real .md twin (src/app/llms.md): docs pages, the blog index and its posts + * (content/blog), the changelog index and its entries (content/changelog/*.mdx). Sorted, so the file + * is deterministic. */ export function generateTwins() { const paths = [ ...docsSource().getPages().map((page) => page.url), + '/blog', ...mdxSlugs('content/blog').map((slug) => `/blog/${slug}`), '/changelog', ...mdxSlugs('content/changelog').map((slug) => `/changelog/${slug}`), diff --git a/src/app/blog/page.tsx b/src/app/blog/page.tsx index 28ae579..4efd920 100644 --- a/src/app/blog/page.tsx +++ b/src/app/blog/page.tsx @@ -1,17 +1,16 @@ import type { Metadata } from 'next'; import Link from 'next/link'; -import { blog } from '@/../.source/server'; import { BlogShell } from '@/components/blog/blog-shell'; import { formatDate, postSlug } from '@/components/blog/post-meta'; -import { BLOG_URL } from '@/lib/site'; +import { BLOG_DESCRIPTION, sortedPosts, type Post } from '@/lib/blog'; +import { BLOG_URL, SITE_URL } from '@/lib/site'; export const metadata: Metadata = { // absolute: the blog lives on affitor.com, so no "| Affitor Docs" suffix. title: { absolute: 'Blog | Affitor' }, - description: - 'Essays, launches, and guides from the team building Affitor — affiliate infrastructure for the agent era.', - // Canonical home of the blog is the proxied affitor.com/blog zone. - alternates: { canonical: BLOG_URL }, + description: BLOG_DESCRIPTION, + // Canonical home of the blog is the proxied affitor.com/blog zone; /blog.md is its machine-readable twin. + alternates: { canonical: BLOG_URL, types: { 'text/markdown': '/blog.md' } }, openGraph: { title: 'Affitor Blog', description: @@ -27,10 +26,28 @@ export const metadata: Metadata = { }, }; -type Post = (typeof blog)[number]; - -function byDateDesc(a: Post, b: Post) { - return new Date(b.date).getTime() - new Date(a.date).getTime(); +/** CollectionPage of every post, in the page's order (same list as /blog.md); each post page has its own BlogPosting. */ +function jsonLd(posts: Post[]) { + return JSON.stringify({ + '@context': 'https://schema.org', + '@type': 'CollectionPage', + '@id': BLOG_URL, + url: BLOG_URL, + name: 'Affitor Blog', + description: BLOG_DESCRIPTION, + publisher: { '@type': 'Organization', name: 'Affitor', url: SITE_URL }, + mainEntity: { + '@type': 'ItemList', + itemListOrder: 'https://schema.org/ItemListOrderDescending', + numberOfItems: posts.length, + itemListElement: posts.map((post, i) => ({ + '@type': 'ListItem', + position: i + 1, + url: `${BLOG_URL}/${postSlug(post.info.path)}`, + name: post.title, + })), + }, + }).replace(/ + {/* eslint-disable-next-line react/no-danger -- server-rendered schema; `<` escaped */} +