Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions next.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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' },
Expand Down
50 changes: 46 additions & 4 deletions scripts/check-agent-surface.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -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(/<link\b[^>]*>/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(/<script\b[^>]*\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',
);
}

/**
Expand Down Expand Up @@ -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);
Expand Down Expand Up @@ -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');

Expand Down
5 changes: 4 additions & 1 deletion scripts/check-docs-host-http.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,8 @@ const ALWAYS = [
[PROXY, '/changelog/invite-partners', 200, null, 'text/html'],
[PROXY, '/changelog.md', 200, null, 'text/markdown'],
[PROXY, '/changelog/invite-partners.md', 200, null, 'text/markdown'],
// The blog index twin (13/11/2026), which affitor.com/blog.md proxies to.
[PROXY, '/blog.md', 200, null, 'text/markdown'],
[PROXY, '/changelog/rss.xml', 200, null, 'application/rss+xml'],
[PROXY, '/changelog.json', 200, null, 'application/json'],
[PROXY, '/changelog/context.md', 200, null, 'text/markdown'],
Expand Down Expand Up @@ -150,7 +152,8 @@ const ALWAYS = [
[PROXY, '/changelog/invite-partners', 200, null, 'text/html', HTML],
[PROXY, '/changelog', 200, null, 'text/markdown', MD],
[PROXY, '/changelog', 200, null, 'text/html', HTML],
[PROXY, '/blog', 200, null, 'text/html', NO_TWIN],
[PROXY, '/blog', 200, null, 'text/markdown', MD],
[PROXY, '/blog', 200, null, 'text/html', HTML],
[PROXY, '/docs/api/search?query=payout', 200, null, 'application/json', NO_TWIN],
[PROXY, '/changelog/rss.xml', 200, null, 'application/rss+xml', NO_TWIN],
[PROXY, '/docs/brand/quickstart.md', 200, null, 'text/markdown', NO_TWIN],
Expand Down
11 changes: 6 additions & 5 deletions scripts/check-docs-host.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -266,15 +266,17 @@ function invariants() {
['/docs', '/docs/index.md'],
['/docs/api-reference/errors', '/docs/api-reference/errors.md'],
['/blog/rewardful-alternatives', '/blog/rewardful-alternatives.md'],
// The blog index has its twin since the blog index twin change (13/11/2026), like the changelog index.
['/blog', '/blog.md'],
['/changelog', '/changelog.md'],
['/changelog?for=brands', '/changelog.md?for=brands'],
['/changelog/invite-partners', '/changelog/invite-partners.md'],
]) check(`${host}${path}: markdown twin ${twin} for Accept: text/markdown, HTML otherwise, Vary: Accept`, negotiates(host, path, twin));
for (const path of [
// Not pages: no twin, even where a .md answers (/changelog/context.md is the AI context pack).
'/docs/no-such-page', '/docs/brand/no-such-page', '/blog/no-such-post', '/changelog/no-such-entry', '/changelog/context',
'/blog', '/docs/api/search', '/docs/openapi.json', '/docs/llms-full.txt', '/docs/brand/quickstart.md', '/docs/skill.md',
'/docs/brand/dashboard.png', '/blog/rewardful-alternatives.md', '/blog/covers/x.png', '/changelog.md', '/changelog/invite-partners.md',
'/docs/api/search', '/docs/openapi.json', '/docs/llms-full.txt', '/docs/brand/quickstart.md', '/docs/skill.md',
'/docs/brand/dashboard.png', '/blog.md', '/blog/rewardful-alternatives.md', '/blog/covers/x.png', '/changelog.md', '/changelog/invite-partners.md',
'/changelog/rss.xml', '/changelog.json', '/changelog/context.md', '/docsy', '/brand/quickstart',
]) check(`${host}${path} has no twin: Accept: text/markdown changes nothing`, untouched(host, path));
// Redirects run before negotiation: the client negotiates again at the new URL.
Expand Down Expand Up @@ -395,14 +397,13 @@ mode('yes', () => {
});
delete process.env.DOCS_HOST_REDIRECT;

check('twin list: docs index, changelog index, every blog post and changelog entry, no twin paths', () => {
check('twin list: docs index, blog index, changelog index, every blog post and changelog entry, no twin paths', () => {
const slugs = (dir) => readdirSync(join(ROOT, dir)).filter((f) => f.endsWith('.mdx')).map((f) => f.slice(0, -4));
for (const path of ['/docs', '/docs/brand/quickstart', '/changelog', ...slugs('content/blog').map((s) => `/blog/${s}`), ...slugs('content/changelog').map((s) => `/changelog/${s}`)]) {
for (const path of ['/docs', '/docs/brand/quickstart', '/blog', '/changelog', ...slugs('content/blog').map((s) => `/blog/${s}`), ...slugs('content/changelog').map((s) => `/changelog/${s}`)]) {
assert.ok(TWIN_PAGES.includes(path), `${path} missing from src/generated/markdown-twins.json`);
}
for (const path of TWIN_PAGES) assert.match(path, /^\/(?:docs|blog|changelog)(?:\/[^.]+)?$/, `${path}: a page path, not a file`);
assert.equal(TWIN_PAGES.includes('/changelog/context'), false);
assert.equal(TWIN_PAGES.includes('/blog'), false);
});
check(`every listed page (${TWIN_PAGES.length}) negotiates on affitor.com`, () => {
for (const path of TWIN_PAGES) {
Expand Down
6 changes: 4 additions & 2 deletions scripts/gen-llms.js
Original file line number Diff line number Diff line change
Expand Up @@ -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}`),
Expand Down
41 changes: 30 additions & 11 deletions src/app/blog/page.tsx
Original file line number Diff line number Diff line change
@@ -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:
Expand All @@ -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(/</g, '\\u003c');
}

function PostCard({ post }: { post: Post }) {
Expand Down Expand Up @@ -78,10 +95,12 @@ function PostCard({ post }: { post: Post }) {
}

export default function BlogIndexPage() {
const posts = [...blog].sort(byDateDesc);
const posts = sortedPosts();

return (
<BlogShell>
{/* eslint-disable-next-line react/no-danger -- server-rendered schema; `<` escaped */}
<script type="application/ld+json" dangerouslySetInnerHTML={{ __html: jsonLd(posts) }} />
<div className="mx-auto w-full max-w-[1152px] px-6 py-16 md:py-24">
<header className="mb-16 md:mb-20">
<p className="text-[13px] font-medium uppercase tracking-[0.04em] text-fd-primary mb-3">
Expand Down
1 change: 1 addition & 0 deletions src/app/llms.md/[[...slug]]/route.ts
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ export async function GET(
export function generateStaticParams(): { slug: string[] }[] {
return [
{ slug: ['index'] },
{ slug: ['blog'] },
{ slug: ['changelog'] },
...source
.generateParams()
Expand Down
6 changes: 2 additions & 4 deletions src/app/sitemap.ts
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
import type { MetadataRoute } from 'next';
import { getAgentPages, type AgentPage } from '@/lib/agent-md';
import { BLOG_URL, DOCS_URL } from '@/lib/site';
import { DOCS_URL } from '@/lib/site';

const newest = (pages: AgentPage[]) =>
pages
Expand All @@ -12,16 +12,14 @@ const newest = (pages: AgentPage[]) =>
export default function sitemap(): MetadataRoute.Sitemap {
const pages = getAgentPages();
const lastModified = newest(pages);
// The blog index (no twin) changes whenever a post does, so it carries the newest post date.
const blogModified = newest(pages.filter((page) => page.type === 'blog'));

// Every page and its .md twin; the blog index is one of them (dated by the newest post, src/lib/agent-md.ts).
return [
...pages.flatMap((page) => {
const html = { url: page.url, ...(page.updated ? { lastModified: page.updated } : {}) };
const md = { url: page.markdownUrl, ...(page.updated ? { lastModified: page.updated } : {}) };
return [html, md];
}),
{ url: BLOG_URL, ...(blogModified ? { lastModified: blogModified } : {}) },
{ url: `${DOCS_URL}/llms.txt`, ...(lastModified ? { lastModified } : {}) },
{ url: `${DOCS_URL}/llms-full.txt`, ...(lastModified ? { lastModified } : {}) },
];
Expand Down
2 changes: 2 additions & 0 deletions src/generated/markdown-twins.json
Original file line number Diff line number Diff line change
@@ -1,4 +1,5 @@
[
"/blog",
"/blog/agent-commerce-attribution-layer",
"/blog/best-affiliate-software-saas",
"/blog/compare",
Expand Down Expand Up @@ -83,6 +84,7 @@
"/changelog/improvements-2026-11-09",
"/changelog/improvements-2026-11-10",
"/changelog/improvements-2026-11-11",
"/changelog/improvements-2026-11-12",
"/changelog/integrations-and-agents",
"/changelog/integrations-hub",
"/changelog/invite-partners",
Expand Down
22 changes: 21 additions & 1 deletion src/lib/agent-md.ts
Original file line number Diff line number Diff line change
@@ -1,8 +1,9 @@
import { source } from '@/lib/source';
import { blog } from '@/../.source/server';
import { postSlug } from '@/components/blog/post-meta';
import { BLOG_DESCRIPTION, sortedPosts } from '@/lib/blog';
import { CHANGELOG_SUB, CHANGELOG_URL, aiContext, entrySlug, entryUrl, openDeprecations, preamble, sortedEntries } from '@/lib/changelog';
import { DOCS_URL, SITE_URL } from '@/lib/site';
import { BLOG_URL, DOCS_URL, SITE_URL } from '@/lib/site';

const FRONTMATTER = /^---\r?\n[\s\S]*?\r?\n---\r?\n/;
// A heading's custom id (`#### Hermes Agent [#hermes]`) is for the page's anchor, not for readers of the twin.
Expand All @@ -27,7 +28,18 @@ export function changelogIndex() {
return `${head}${open.length ? `## Open deprecations\n\n${open.join('\n')}\n\n` : ''}## Entries\n\n${lines.join('\n')}\n`;
}

/** Body of /blog.md: one line per post, in the page's order. check-agent-surface.mjs rebuilds the same text from the sources. */
export function blogIndex() {
const lines = sortedPosts().map(
(p) => `- ${p.date} · ${p.category} · [${p.title}](${BLOG_URL}/${postSlug(p.info.path)}): ${p.description}`,
);
return `# Affitor Blog\n\n> ${BLOG_DESCRIPTION}\n\n## Posts\n\n${lines.join('\n')}\n`;
}

async function renderBody(slug: string[]): Promise<string | null> {
// /blog.md: one line per post (each post has its own twin).
if (slug.length === 1 && slug[0] === 'blog') return blogIndex();

// /blog/<slug>.md
if (slug[0] === 'blog' && slug.length === 2) {
const post = blog.find((p) => postSlug(p.info.path) === slug[1]);
Expand Down Expand Up @@ -135,9 +147,17 @@ function changelogPages(): AgentPage[] {
];
}

/** The blog index and its twin /blog.md; it changes whenever a post does, so it carries the newest post date. */
function blogIndexPage(): AgentPage {
const updated = blog.map((post) => post.updated ?? post.date).sort().at(-1);
assertDates(updated ? [updated] : [], 'blog');
return { id: 'blog', type: 'blog', url: BLOG_URL, markdownUrl: `${BLOG_URL}.md`, updated };
}

export function getAgentPages(): AgentPage[] {
return [
...source.getPages().map(getDocMetadata),
blogIndexPage(),
...blog.map((post): AgentPage => {
const id = `blog/${postSlug(post.info.path)}`;
const updated = post.updated ?? post.date;
Expand Down
16 changes: 16 additions & 0 deletions src/lib/blog.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
import { blog } from '@/../.source/server';
import { postSlug } from '@/components/blog/post-meta';

export type Post = (typeof blog)[number];

/** The blog index description: page metadata, its CollectionPage and /blog.md (check-agent-surface.mjs mirrors it). */
export const BLOG_DESCRIPTION =
'Essays, launches, and guides from the team building Affitor — affiliate infrastructure for the agent era.';

/**
* The blog index order everywhere (the page, its JSON-LD, /blog.md): newest first, then by slug, so posts of the
* same day keep one order (CORE-690 follow-up, 13/11/2026).
*/
export function sortedPosts(): Post[] {
return [...blog].sort((a, b) => b.date.localeCompare(a.date) || postSlug(a.info.path).localeCompare(postSlug(b.info.path)));
}
Loading