Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

docs changelog (#2645)

shagun-singh-inkeepa1eac2e42e4f
diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.yml
index 9c02f2253..80119b61d 100644
--- a/.github/workflows/desktop-release.yml
+++ b/.github/workflows/desktop-release.yml
@@ -495,6 +495,13 @@ jobs:
echo "Promoted ${RELEASE_TAG} to published (draft=false, latest=false; channel=${CHANNEL})."
fi
+ # The on-site changelog (/docs/changelog) is rebuilt by
+ # public-open-knowledge-docs-changelog-deploy.yml (on agents-private), which
+ # fires the Vercel deploy hook when the `main-reset` commit rewrites
+ # packages/cli/CHANGELOG.md on main. Triggering here would be too early — the
+ # changelog reads that file, and it isn't updated until main-reset lands after
+ # this release completes.
+
# Announce STABLE releases to Slack. Gated on channel=latest so betas
# stay silent — every *-beta.N cut also flows through this job (on
# channel=beta) and must not post (see Detect channel step above).
diff --git a/docs/content/meta.json b/docs/content/meta.json
index 1c24cbd65..c6e8399f0 100644
--- a/docs/content/meta.json
+++ b/docs/content/meta.json
@@ -2,6 +2,7 @@
"title": "OpenKnowledge",
"icon": "LuBookOpen",
"pages": [
+ "[LuHistory][Changelog](/docs/changelog)",
"---GET STARTED---",
"...get-started",
"---USE CASES---",
diff --git a/docs/package.json b/docs/package.json
index c5ff5a0cf..3cf9e343b 100644
--- a/docs/package.json
+++ b/docs/package.json
@@ -30,6 +30,7 @@
"fumadocs-ui": "~16.1.0",
"katex": "^0.16.22",
"lucide-react": "^0.503.0",
+ "marked": "^18.0.6",
"mermaid": "^11.12.3",
"next": "^16",
"next-themes": "^0.4.6",
diff --git a/docs/src/app/docs/changelog/[tag]/page.tsx b/docs/src/app/docs/changelog/[tag]/page.tsx
new file mode 100644
index 000000000..d97cd8080
--- /dev/null
+++ b/docs/src/app/docs/changelog/[tag]/page.tsx
@@ -0,0 +1,96 @@
+import { DocsBody, DocsDescription, DocsPage, DocsTitle } from 'fumadocs-ui/page';
+import type { Metadata } from 'next';
+import { notFound } from 'next/navigation';
+import { getChangelogSource, getReleasePages } from '@/lib/changelog-source';
+import { CHANGELOG_ROUTE, metaDescription, SITE_NAME, SITE_URL } from '@/lib/site';
+
+/**
+ * `/docs/changelog/<tag>` — one indexable page per stable release.
+ *
+ * These pages exist for search-engine indexing: every release gets its own URL in
+ * the sitemap even though the timeline at `/docs/changelog` links only to anchors,
+ * not to these pages. Data comes from the same build-time changelog source adapter;
+ * `dynamic = 'force-static'` + `dynamicParams = false` prerender exactly the known
+ * tags as static HTML and 404 anything else (so the sibling `rss.xml` route is
+ * never shadowed).
+ */
+export const dynamic = 'force-static';
+export const dynamicParams = false;
+
+export async function generateStaticParams() {
+ const source = await getChangelogSource();
+ return getReleasePages(source).map((page) => ({ tag: page.slugs[0] }));
+}
+
+export async function generateMetadata(
+ props: PageProps<'/docs/changelog/[tag]'>,
+): Promise<Metadata> {
+ const { tag } = await props.params;
+ const source = await getChangelogSource();
+ const release = source.getPage([tag])?.data.releases[0];
+ if (!release) notFound();
+
+ const url = `${CHANGELOG_ROUTE}/${tag}`;
+ const description = metaDescription(
+ `Release notes for ${SITE_NAME} ${release.tag}${
+ release.publishedAt ? `, published ${formatDate(release.publishedAt)}` : ''
+ }.`,
+ );
+
+ return {
+ title: `${release.title} · Changelog`,
+ description,
+ alternates: { canonical: `${SITE_URL}${url}` },
+ openGraph: {
+ type: 'article',
+ siteName: SITE_NAME,
+ title: `${release.title} · ${SITE_NAME} Changelog`,
+ description,
+ url: `${SITE_URL}${url}`,
+ },
+ };
+}
+
+export default async function ReleasePage(props: PageProps<'/docs/changelog/[tag]'>) {
+ const { tag } = await props.params;
+ const source = await getChangelogSource();
+ const release = source.getPage([tag])?.data.releases[0];
+ if (!release) notFound();
+
+ const date = formatDate(release.publishedAt);
+
+ return (
+ <DocsPage article={{ className: 'pb-12' }}>
+ <DocsTitle>{release.title}</DocsTitle>
+ <DocsDescription>
+ {date ? `Released ${date}. ` : ''}
+ Part of the <a href={CHANGELOG_ROUTE}>{SITE_NAME} changelog</a>.
+ </DocsDescription>
+ <DocsBody>
+ {release.bodyHtml ? (
+ // biome-ignore lint/security/noDangerouslySetInnerHtml: trusted maintainer-authored release notes, rendered at build time
+ <div dangerouslySetInnerHTML={{ __html: release.bodyHtml }} />
+ ) : (
+ <p>No notes for this release.</p>
+ )}
+ <p>
+ <a href={release.htmlUrl} target="_blank" rel="noreferrer">
+ View {release.tag} on GitHub
+ </a>
+ </p>
+ </DocsBody>
+ </DocsPage>
+ );
+}
+
+function formatDate(iso: string | null): string | null {
+ if (!iso) return null;
+ const ms = Date.parse(iso);
+ if (Number.isNaN(ms)) return null;
+ return new Intl.DateTimeFormat('en-US', {
+ year: 'numeric',
+ month: 'short',
+ day: 'numeric',
+ timeZone: 'UTC',
+ }).format(ms);
+}
diff --git a/docs/src/app/docs/changelog/page.tsx b/docs/src/app/docs/changelog/page.tsx
new file mode 100644
index 000000000..c1cc4b381
--- /dev/null
+++ b/docs/src/app/docs/changelog/page.tsx
@@ -0,0 +1,75 @@
+import { DocsDescription, DocsPage, DocsTitle } from 'fumadocs-ui/page';
+import type { Metadata } from 'next';
+import { ChangelogTimeline } from '@/components/changelog-timeline';
+import { getChangelogSource } from '@/lib/changelog-source';
+import {
+ CHANGELOG_ROUTE,
+ metaDescription,
+ RELEASES_PAGE_URL,
+ SITE_NAME,
+ SITE_URL,
+} from '@/lib/site';
+
+/**
+ * `/docs/changelog` — the stable release notes.
+ *
+ * Data comes from the Fumadocs changelog source adapter (`getChangelogSource`),
+ * which reads packages/cli/CHANGELOG.md at build time (dates come from a small
+ * best-effort GitHub call). `dynamic = 'force-static'` makes that happen once during
+ * the build and bakes the result into static HTML — fully indexable, no runtime
+ * dependency. A stable release refreshes it because the `main-reset` commit that
+ * rewrites CHANGELOG.md triggers a docs rebuild (see
+ * `public-open-knowledge-docs-changelog-deploy.yml`). Living under `app/docs/` puts
+ * the page inside the shared `DocsLayout` (sidebar + search); this static segment
+ * takes precedence over the `[...slug]` MDX catch-all.
+ */
+export const dynamic = 'force-static';
+
+const PAGE_TITLE = 'Changelog';
+const PAGE_DESCRIPTION = `Stable releases of ${SITE_NAME}, newest first, with the notes for every version.`;
+const RSS_ROUTE = `${CHANGELOG_ROUTE}/rss.xml`;
+
+export const metadata: Metadata = {
+ title: PAGE_TITLE,
+ description: metaDescription(PAGE_DESCRIPTION),
+ alternates: {
+ canonical: `${SITE_URL}${CHANGELOG_ROUTE}`,
+ types: { 'application/rss+xml': `${SITE_URL}${RSS_ROUTE}` },
+ },
+ openGraph: {
+ title: `${PAGE_TITLE} · ${SITE_NAME}`,
+ description: metaDescription(PAGE_DESCRIPTION),
+ url: `${SITE_URL}${CHANGELOG_ROUTE}`,
+ },
+};
+
+export default async function ChangelogPage() {
+ // `getChangelogSource` parses CHANGELOG.md at build time. In a normal deploy the
+ // file is present so `releases` is populated; in the public mirror (CHANGELOG.md
+ // excluded) it resolves empty and the timeline just renders nothing.
+ const source = await getChangelogSource();
+ const releases = source.getPage([])?.data.releases ?? [];
+
+ // Anchors mirror the timeline's per-release section ids.
+ const toc = releases.map((release) => ({
+ title: release.title,
+ url: `#${release.tag}`,
+ depth: 2,
+ }));
+
+ return (
+ <DocsPage toc={toc} tableOfContent={{ style: 'clerk' }} article={{ className: 'pb-12' }}>
+ <DocsTitle>{PAGE_TITLE}</DocsTitle>
+ <DocsDescription>
+ Stable releases, newest first, with notes for every version. Also published on{' '}
+ <a href={RELEASES_PAGE_URL} target="_blank" rel="noreferrer">
+ GitHub
+ </a>
+ .
+ </DocsDescription>
+ {/* Outside DocsBody on purpose — the timeline owns its own chrome and
+ scopes `prose` to the notes (see ChangelogTimeline). */}
+ <ChangelogTimeline releases={releases} />
+ </DocsPage>
+ );
+}
diff --git a/docs/src/app/docs/changelog/rss.xml/route.ts b/docs/src/app/docs/changelog/rss.xml/route.ts
new file mode 100644
index 000000000..885957401
--- /dev/null
+++ b/docs/src/app/docs/changelog/rss.xml/route.ts
@@ -0,0 +1,80 @@
+import { getChangelogSource } from '@/lib/changelog-source';
+import { CHANGELOG_ROUTE, SITE_NAME, SITE_URL } from '@/lib/site';
+
+/**
+ * RSS 2.0 feed for `/docs/changelog`, built from the same memoized changelog
+ * source the page + sitemap render from — one paginated GitHub fetch per build,
+ * no drift, no runtime GitHub call. `force-static` prerenders the feed at build
+ * time and serves it from the CDN rather than invoking a function per request; a
+ * stable release refreshes it via the docs rebuild (see `desktop-release.yml`).
+ */
+export const dynamic = 'force-static';
+
+const FEED_URL = `${SITE_URL}${CHANGELOG_ROUTE}/rss.xml`;
+const PAGE_URL = `${SITE_URL}${CHANGELOG_ROUTE}`;
+
+/** Escape the five XML predefined entities for use in element text. */
+function escapeXml(value: string): string {
+ return value
+ .replace(/&/g, '&amp;')
+ .replace(/</g, '&lt;')
+ .replace(/>/g, '&gt;')
+ .replace(/"/g, '&quot;')
+ .replace(/'/g, '&apos;');
+}
+
+/**
+ * Notes are HTML and go in a CDATA section, so the only thing that can break the
+ * document is a literal `]]>` inside the payload — split it across two sections.
+ */
+function cdata(html: string): string {
+ return `<![CDATA[${html.replace(/]]>/g, ']]]]><![CDATA[>')}]]>`;
+}
+
+/** RFC-822 date, which the RSS 2.0 spec requires for `pubDate`. */
+function rfc822(iso: string | null): string | null {
+ if (!iso) return null;
+ const ms = Date.parse(iso);
+ return Number.isNaN(ms) ? null : new Date(ms).toUTCString();
+}
+
+export async function GET(): Promise<Response> {
+ // Read the memoized changelog source (shared with the page + sitemap) instead
+ // of fetching the releases feed again — one paginated GitHub walk per build,
+ // not two. The index page already carries the newest-window cap.
+ const source = await getChangelogSource();
+ const releases = source.getPage([])?.data.releases ?? [];
+ const items = releases
+ .map((release) => {
+ const pubDate = rfc822(release.publishedAt);
+ return [
+ ' <item>',
+ ` <title>${escapeXml(release.title)}</title>`,
+ ` <link>${escapeXml(release.htmlUrl)}</link>`,
+ ` <guid isPermaLink="true">${escapeXml(release.htmlUrl)}</guid>`,
+ pubDate ? ` <pubDate>${pubDate}</pubDate>` : null,
+ ` <description>${cdata(release.bodyHtml)}</description>`,
+ ' </item>',
+ ]
+ .filter(Boolean)
+ .join('\n');
+ })
+ .join('\n');
+
+ const xml = `<?xml version="1.0" encoding="UTF-8"?>
+<rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">
+ <channel>
+ <title>${escapeXml(`${SITE_NAME} Changelog`)}</title>
+ <link>${PAGE_URL}</link>
+ <description>${escapeXml(`Stable releases of ${SITE_NAME}.`)}</description>
+ <language>en</language>
+ <atom:link href="${FEED_URL}" rel="self" type="application/rss+xml" />
+${items}
+ </channel>
+</rss>
+`;
+
+ return new Response(xml, {
+ headers: { 'content-type': 'application/rss+xml; charset=utf-8' },
+ });
+}
diff --git a/docs/src/app/sitemap.ts b/docs/src/app/sitemap.ts
index 8edf5f04b..5532fe3b7 100644
--- a/docs/src/app/sitemap.ts
+++ b/docs/src/app/sitemap.ts
@@ -1,20 +1,33 @@
import type { MetadataRoute } from 'next';
import { BRAND_ROUTE } from '@/lib/brand-assets';
-import { SITE_URL } from '@/lib/site';
+import { getChangelogSource, getReleasePages } from '@/lib/changelog-source';
+import { CHANGELOG_ROUTE, SITE_URL } from '@/lib/site';
import { source } from '@/lib/source';
-export default function sitemap(): MetadataRoute.Sitemap {
+export default async function sitemap(): Promise<MetadataRoute.Sitemap> {
const docPages = source.getPages().map((page) => ({
url: `${SITE_URL}${page.url}`,
changeFrequency: 'weekly' as const,
priority: 0.7,
}));
+ // Every stable release gets its own indexable URL here even though the timeline
+ // links only to anchors, not to these pages — the sitemap is how search engines
+ // discover them. Built from the same build-time changelog source as the pages.
+ const changelogSource = await getChangelogSource();
+ const releasePages = getReleasePages(changelogSource).map((page) => ({
+ url: `${SITE_URL}${page.url}`,
+ changeFrequency: 'monthly' as const,
+ priority: 0.5,
+ }));
+
// /sitemap.xml is served by docs (the default zone) — marketing claims only
// `/` + /marketing-assets/*, so this docs sitemap is the canonical public one
// and must list the apex (rendered by the marketing zone) plus /brand + docs.
return [
{ url: SITE_URL, changeFrequency: 'weekly', priority: 1.0 },
+ { url: `${SITE_URL}${CHANGELOG_ROUTE}`, changeFrequency: 'weekly', priority: 0.6 },
+ ...releasePages,
{ url: `${SITE_URL}${BRAND_ROUTE}`, changeFrequency: 'monthly', priority: 0.4 },
...docPages,
];
diff --git a/docs/src/components/changelog-timeline.tsx b/docs/src/components/changelog-timeline.tsx
new file mode 100644
index 000000000..8c9459db7
--- /dev/null
+++ b/docs/src/components/changelog-timeline.tsx
@@ -0,0 +1,103 @@
+import type { ReleaseNote } from '@/lib/releases';
+import { CHANGELOG_ROUTE } from '@/lib/site';
+
+/**
+ * Vertical release timeline: a sticky version/date rail on the left, notes on the
+ * right — the Mintlify `<Update>` treatment. Each version links to its own
+ * `/docs/changelog/<tag>` page (the internal link that keeps those pages
+ * indexable rather than sitemap-only orphans).
+ *
+ * `bodyHtml` is trusted: GitHub release notes are authored by maintainers at
+ * publish time, the same trust boundary as the docs content itself (cf. the
+ * mermaid/katex render sites). It is rendered at build time from the changelog
+ * source adapter's GitHub fetch, never fetched in the browser.
+ *
+ * Deliberately rendered OUTSIDE `DocsBody`: Tailwind Typography's `not-prose`
+ * excludes every descendant, so a `not-prose` shell with a nested `prose` notes
+ * block cannot re-enable prose. Instead the timeline owns its own chrome and
+ * applies `prose` only to the notes.
+ */
+export function ChangelogTimeline({ releases }: { releases: ReleaseNote[] }) {
+ return (
+ <div className="flex flex-col">
+ {releases.map((release) => (
+ <ChangelogEntry key={release.tag} release={release} />
+ ))}
+ </div>
+ );
+}
+
+function ChangelogEntry({ release }: { release: ReleaseNote }) {
+ const date = formatDate(release.publishedAt);
+
+ return (
+ <section
+ id={release.tag}
+ className="group relative scroll-mt-24 pb-10 md:grid md:grid-cols-[10rem_1fr] md:gap-8"
+ >
+ {/* Left rail: sticky version + date, with the timeline node and connector.
+ The connector is drawn on the rail (not the whole row) so it lines up
+ with the node at every viewport. */}
+ <div className="relative md:sticky md:top-24 md:self-start md:pb-10">
+ <div
+ aria-hidden="true"
+ className="absolute top-2 -right-4 hidden h-full w-px bg-fd-border group-last:hidden md:block"
+ />
+ <div
+ aria-hidden="true"
+ className="absolute top-1.5 -right-[1.1875rem] hidden size-2.5 rounded-full border-2 border-fd-background bg-fd-primary md:block"
+ />
+ {/* The version links to its own /docs/changelog/<tag> page. That internal
+ link is what lets search engines discover + index each release's
+ standalone page rather than leaving it a sitemap-only orphan. The
+ section keeps its `id` (below) so the in-page ToC still anchors to it. */}
+ <a
+ href={`${CHANGELOG_ROUTE}/${release.tag}`}
+ className="font-mono text-sm font-medium text-fd-foreground no-underline transition-colors hover:text-fd-primary"
+ >
+ {release.title}
+ </a>
+ {date ? (
+ <time
+ dateTime={release.publishedAt ?? undefined}
+ className="mt-1 block text-xs text-fd-muted-foreground"
+ >
+ {date}
+ </time>
+ ) : null}
+ </div>
+
+ <div className="mt-3 min-w-0 md:mt-0">
+ {release.bodyHtml ? (
+ <div
+ className="prose max-w-none prose-headings:mt-6 prose-headings:mb-2 first:prose-headings:mt-0"
+ // biome-ignore lint/security/noDangerouslySetInnerHtml: trusted maintainer-authored release notes, rendered at build time
+ dangerouslySetInnerHTML={{ __html: release.bodyHtml }}
+ />
+ ) : (
+ <p className="text-sm text-fd-muted-foreground">No notes for this release.</p>
+ )}
+ <a
+ href={release.htmlUrl}
+ target="_blank"
+ rel="noreferrer"
+ className="mt-4 inline-block text-xs text-fd-muted-foreground underline underline-offset-4 transition-colors hover:text-fd-foreground"
+ >
+ View on GitHub
+ </a>
+ </div>
+ </section>
+ );
+}
+
+function formatDate(iso: string | null): string | null {
+ if (!iso) return null;
+ const ms = Date.parse(iso);
+ if (Number.isNaN(ms)) return null;
+ return new Intl.DateTimeFormat('en-US', {
+ year: 'numeric',
+ month: 'short',
+ day: 'numeric',
+ timeZone: 'UTC',
+ }).format(ms);
+}
diff --git a/docs/src/components/footer.tsx b/docs/src/components/footer.tsx
index 63befdc0a..5e9404d17 100644
--- a/docs/src/components/footer.tsx
+++ b/docs/src/components/footer.tsx
@@ -4,7 +4,7 @@ import { GitHubIcon } from '@/components/icons/github';
import { XIcon } from '@/components/icons/x';
import { InkeepLogo } from '@/components/inkeep-logo';
import { BRAND_ROUTE } from '@/lib/brand-assets';
-import { DISCORD_URL, GITHUB_URL, X_URL } from '@/lib/site';
+import { CHANGELOG_ROUTE, DISCORD_URL, GITHUB_URL, X_URL } from '@/lib/site';
import { DotTexture } from './dot-texture';
const socialLinks = [
@@ -14,6 +14,7 @@ const socialLinks = [
];
const legalLinks = [
+ { href: CHANGELOG_ROUTE, label: 'Changelog', external: false },
{ href: BRAND_ROUTE, label: 'Brand', external: false },
{
href: 'https://inkeep.com/policies/terms-of-service',
diff --git a/docs/src/lib/changelog-source.test.ts b/docs/src/lib/changelog-source.test.ts
new file mode 100644
index 000000000..7cfed19a2
--- /dev/null
+++ b/docs/src/lib/changelog-source.test.ts
@@ -0,0 +1,59 @@
+import { describe, expect, test } from 'vitest';
+import { buildChangelogSourceFiles } from './changelog-source.ts';
+import type { ReleaseNote } from './releases.ts';
+import { CHANGELOG_TIMELINE_LIMIT } from './site.ts';
+
+function note(tag: string): ReleaseNote {
+ return {
+ tag,
+ title: tag,
+ publishedAt: '2026-07-01T00:00:00Z',
+ bodyHtml: `<p>${tag}</p>`,
+ htmlUrl: `https://github.com/inkeep/open-knowledge/releases/tag/${tag}`,
+ };
+}
+
+type Files = ReturnType<typeof buildChangelogSourceFiles>['files'];
+type PageFile = Extract<Files[number], { type: 'page' }>;
+
+const isPage = (f: Files[number]): f is PageFile => f.type === 'page';
+
+/** All page files with a single slug segment — the per-release `[tag]` pages. */
+function releasePages(files: Files): PageFile[] {
+ return files.filter(isPage).filter((f) => f.slugs?.length === 1);
+}
+
+/** The lone index page (slugs `[]`). */
+function indexPage(files: Files): PageFile | undefined {
+ return files.filter(isPage).find((f) => f.slugs?.length === 0);
+}
+
+describe('buildChangelogSourceFiles', () => {
+ test('caps the index timeline but emits a page for every release', () => {
+ const releases = Array.from({ length: CHANGELOG_TIMELINE_LIMIT + 12 }, (_, i) =>
+ note(`v0.${i}.0`),
+ );
+ const { files } = buildChangelogSourceFiles(releases);
+
+ // Timeline is capped...
+ expect(indexPage(files)?.data.releases).toHaveLength(CHANGELOG_TIMELINE_LIMIT);
+ // ...but every release keeps its own indexable page (sitemap/[tag] stay complete).
+ expect(releasePages(files)).toHaveLength(releases.length);
+ });
+
+ test('shows the NEWEST releases on the timeline (fetch is already newest-first)', () => {
+ const releases = Array.from({ length: CHANGELOG_TIMELINE_LIMIT + 5 }, (_, i) =>
+ note(`v0.${i}.0`),
+ );
+ const shown = indexPage(buildChangelogSourceFiles(releases).files)?.data.releases ?? [];
+ expect(shown[0]?.tag).toBe('v0.0.0');
+ expect(shown.at(-1)?.tag).toBe(`v0.${CHANGELOG_TIMELINE_LIMIT - 1}.0`);
+ });
+
+ test('does not cap when there are fewer releases than the limit', () => {
+ const releases = [note('v1.0.0'), note('v0.9.0')];
+ const { files } = buildChangelogSourceFiles(releases);
+ expect(indexPage(files)?.data.releases).toHaveLength(2);
+ expect(releasePages(files)).toHaveLength(2);
+ });
+});
diff --git a/docs/src/lib/changelog-source.ts b/docs/src/lib/changelog-source.ts
new file mode 100644
index 000000000..03a796c09
--- /dev/null
+++ b/docs/src/lib/changelog-source.ts
@@ -0,0 +1,98 @@
+import { loader, type MetaData, type Source } from 'fumadocs-core/source';
+import { loadStableReleases, type ReleaseNote } from '@/lib/releases';
+import { CHANGELOG_TIMELINE_LIMIT } from '@/lib/site';
+
+/**
+ * Build-time Fumadocs source adapter for `/docs/changelog`.
+ *
+ * The changelog has no bespoke committed artifact: this adapter reads the CLI
+ * package's CHANGELOG.md at build time (see `loadStableReleases`) and turns it into
+ * a Fumadocs `Source`. A stable release refreshes it because the `main-reset`
+ * commit that rewrites CHANGELOG.md is a push to the repo the docs build from.
+ * Publish dates come from a small best-effort GitHub API call; the content does
+ * not depend on the network.
+ *
+ * The source emits two kinds of page:
+ * - the index (`/docs/changelog`, slugs `[]`) carrying the newest
+ * `CHANGELOG_TIMELINE_LIMIT` releases — the timeline the site renders. The cap
+ * keeps the timeline bounded as releases accumulate; older releases stay
+ * reachable via their own pages below, not the timeline.
+ * - one page per release (`/docs/changelog/<tag>`, slugs `[<tag>]`), each a real
+ * static URL, for EVERY stable release (not just the timeline's window). They
+ * are deliberately NOT the only link — each timeline entry links to its page —
+ * so every version keeps its own indexable URL in the sitemap for search
+ * engines even after it scrolls off the timeline. The `[tag]` route and
+ * `sitemap.ts` enumerate them via `getPages()`.
+ *
+ * `loader()` is synchronous, so the async load is resolved here first and the built
+ * `Source` handed to it. Callers `await` this inside static
+ * (`dynamic = 'force-static'`) routes, so it runs once at build time and the output
+ * is baked into static HTML — fully indexable, no runtime dependency.
+ *
+ * Memoized as a module-level promise (NOT React `cache()`, which only dedupes within
+ * a single render): a build prerenders the index, the RSS feed, and one page per
+ * release — each a separate render that would otherwise re-read the file and re-run
+ * the date lookup. The singleton collapses them to ONE load per build worker.
+ */
+
+/**
+ * Data carried by a changelog virtual page. The index page holds the whole window;
+ * a per-release page holds just its own release (`releases[0]`).
+ */
+export interface ChangelogPageData {
+ title: string;
+ releases: ReleaseNote[];
+}
+
+export type ChangelogSource = Awaited<ReturnType<typeof getChangelogSource>>;
+
+let cachedSource: ReturnType<typeof buildChangelogSource> | undefined;
+
+export function getChangelogSource() {
+ cachedSource ??= buildChangelogSource();
+ return cachedSource;
+}
+
+async function buildChangelogSource() {
+ // `loadStableReleases` returns [] only when CHANGELOG.md is absent (the public
+ // mirror excludes it), and throws if the file is present but malformed — so an
+ // empty list here is the legitimate mirror case and builds an empty changelog.
+ const releases = await loadStableReleases();
+ return loader({ baseUrl: '/docs/changelog', source: buildChangelogSourceFiles(releases) });
+}
+
+/**
+ * Assemble the Fumadocs `Source` from resolved releases. Pure and network-free
+ * (mirrors `pickStableReleases`) so the timeline-window cap vs. full-page-set
+ * split is unit-testable without a GitHub fetch.
+ *
+ * The index page carries only the newest `CHANGELOG_TIMELINE_LIMIT` releases (the
+ * timeline); a per-release page is emitted for EVERY release, so the sitemap and
+ * `[tag]` routes stay complete no matter how many releases scroll off the
+ * timeline.
+ */
+export function buildChangelogSourceFiles(
+ releases: ReleaseNote[],
+): Source<{ pageData: ChangelogPageData; metaData: MetaData }> {
+ return {
+ files: [
+ {
+ type: 'page',
+ path: 'index.mdx',
+ slugs: [],
+ data: { title: 'Changelog', releases: releases.slice(0, CHANGELOG_TIMELINE_LIMIT) },
+ },
+ ...releases.map((release) => ({
+ type: 'page' as const,
+ path: `${release.tag}.mdx`,
+ slugs: [release.tag],
+ data: { title: release.title, releases: [release] },
+ })),
+ ],
+ };
+}
+
+/** Every per-release page (slug `[<tag>]`), excluding the index — the sitemap set. */
+export function getReleasePages(source: ChangelogSource) {
+ return source.getPages().filter((page) => page.slugs.length === 1);
+}
diff --git a/docs/src/lib/releases.test.ts b/docs/src/lib/releases.test.ts
new file mode 100644
index 000000000..fc32b1a74
--- /dev/null
+++ b/docs/src/lib/releases.test.ts
@@ -0,0 +1,149 @@
+import { describe, expect, test } from 'vitest';
+import { collectDates, fetchReleaseDates, parseChangelog } from './releases.ts';
+
+const SAMPLE = `# @inkeep/open-knowledge
+
+## 0.35.0
+
+### Minor Changes
+
+- 3c124b0: Added the command palette.
+
+### Patch Changes
+
+- 6681a97: Fixed a clone bug.
+
+## 0.34.0
+
+### Patch Changes
+
+- 95380ab: Recorded the server exit reason.
+
+## 0.9.1
+
+### Patch Changes
+
+- deadbeef: Old release.
+`;
+
+describe('parseChangelog', () => {
+ test('parses each version section, newest first (file order)', () => {
+ const out = parseChangelog(SAMPLE);
+ expect(out.map((r) => r.tag)).toEqual(['v0.35.0', 'v0.34.0', 'v0.9.1']);
+ });
+
+ test('derives tag, title, and htmlUrl from the version', () => {
+ const [first] = parseChangelog(SAMPLE);
+ expect(first.tag).toBe('v0.35.0');
+ expect(first.title).toBe('v0.35.0');
+ expect(first.htmlUrl).toBe('https://github.com/inkeep/open-knowledge/releases/tag/v0.35.0');
+ });
+
+ test('strips the changeset commit-hash prefix and renders GFM to HTML', () => {
+ const [first] = parseChangelog(SAMPLE);
+ expect(first.bodyHtml).toContain('<h3');
+ expect(first.bodyHtml).toContain('<li>Added the command palette.</li>');
+ expect(first.bodyHtml).not.toContain('3c124b0');
+ });
+
+ test('injects dates by tag; missing tags get null', () => {
+ const dates = new Map([['v0.35.0', '2026-07-20T13:57:49Z']]);
+ const out = parseChangelog(SAMPLE, dates);
+ expect(out.find((r) => r.tag === 'v0.35.0')?.publishedAt).toBe('2026-07-20T13:57:49Z');
+ expect(out.find((r) => r.tag === 'v0.34.0')?.publishedAt).toBeNull();
+ });
+
+ test('ignores content before the first version heading', () => {
+ const [first] = parseChangelog(SAMPLE);
+ expect(first.bodyHtml).not.toContain('@inkeep/open-knowledge');
+ });
+
+ test('does not match prerelease headings or malformed input', () => {
+ expect(parseChangelog('## 0.30.1-beta.1\n\n- x: note\n')).toEqual([]);
+ expect(parseChangelog('# Title only\n\nno versions here')).toEqual([]);
+ expect(parseChangelog('')).toEqual([]);
+ });
+});
+
+/** A GitHub "list releases" entry, dates-relevant fields only. */
+function apiRelease(
+ tag: string,
+ opts: { draft?: boolean; prerelease?: boolean; published_at?: string | null } = {},
+) {
+ const { draft = false, prerelease = false, published_at = '2026-07-01T00:00:00Z' } = opts;
+ return { tag_name: tag, draft, prerelease, published_at };
+}
+
+describe('collectDates', () => {
+ test('collects stable published dates, skipping drafts and prereleases', () => {
+ const dates = new Map<string, string>();
+ collectDates(
+ [
+ apiRelease('v0.35.0'),
+ apiRelease('v0.35.0-beta.1', { prerelease: true }),
+ apiRelease('v0.29.9', { draft: true }),
+ apiRelease('v0.34.0'),
+ ],
+ dates,
+ 30,
+ );
+ expect([...dates.keys()]).toEqual(['v0.35.0', 'v0.34.0']);
+ });
+
+ test('honors the limit and tolerates malformed entries', () => {
+ const dates = new Map<string, string>();
+ collectDates([apiRelease('v1.0.0'), apiRelease('v0.9.0')], dates, 1);
+ expect(dates.size).toBe(1);
+ const d2 = new Map<string, string>();
+ collectDates([null, 42, { tag_name: 5 }, apiRelease('v1.0.0', { published_at: null })], d2, 30);
+ expect(d2.size).toBe(0);
+ collectDates('not-an-array', d2, 30);
+ expect(d2.size).toBe(0);
+ });
+});
+
+function mockFetch(responder: (page: number) => Response) {
+ const pages: number[] = [];
+ return ((url: string | URL) => {
+ const page = Number(/[?&]page=(\d+)/.exec(String(url))?.[1] ?? '1');
+ pages.push(page);
+ return Promise.resolve(responder(page));
+ }) as unknown as typeof fetch;
+}
+
+const json = (data: unknown) => new Response(JSON.stringify(data), { status: 200 });
+const fullPage = (page: number) =>
+ Array.from({ length: 100 }, (_, i) => apiRelease(`v9.${page}.${i}`, { prerelease: i > 0 }));
+
+describe('fetchReleaseDates (best-effort)', () => {
+ test('paginates until it has enough stable dates, then stops', async () => {
+ // Each full page carries 1 stable + 99 betas, so reaching 2 dates needs 2 pages.
+ const dates = await fetchReleaseDates(
+ 2,
+ mockFetch((p) => json(fullPage(p))),
+ );
+ expect(dates.size).toBe(2);
+ });
+
+ test('stops on a short (final) page', async () => {
+ const dates = await fetchReleaseDates(
+ 30,
+ mockFetch(() => json([apiRelease('v1.0.0')])),
+ );
+ expect(dates.size).toBe(1);
+ });
+
+ test('degrades to empty on HTTP error — never throws', async () => {
+ const dates = await fetchReleaseDates(
+ 30,
+ mockFetch(() => new Response('nope', { status: 500 })),
+ );
+ expect(dates.size).toBe(0);
+ });
+
+ test('degrades to empty on a network throw — never throws', async () => {
+ const dates = await fetchReleaseDates(30, (() =>
+ Promise.reject(new Error('offline'))) as never);
+ expect(dates.size).toBe(0);
+ });
+});
diff --git a/docs/src/lib/releases.ts b/docs/src/lib/releases.ts
new file mode 100644
index 000000000..b5f0a309a
--- /dev/null
+++ b/docs/src/lib/releases.ts
@@ -0,0 +1,222 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { marked } from 'marked';
+
+/**
+ * Stable-release data layer for `/docs/changelog`.
+ *
+ * CONTENT comes from the published CLI package's CHANGELOG.md, which the
+ * `main-reset` workflow rewrites via `changeset version` on every stable release.
+ * So the notes are derived from a file already in the repo — no API pagination, no
+ * feed-walk, no build-time failure when GitHub is unreachable. Betas never touch
+ * CHANGELOG.md (transient, never-committed version override), so the `## X.Y.Z`
+ * sections are stable-only by construction.
+ *
+ * DATES aren't in CHANGELOG.md, and the docs build from agents-private, which does
+ * NOT carry the `vX.Y.Z` release tags (those live on the public mirror where
+ * `promote-stable` creates them). So dates come from a small, bounded GitHub API
+ * call — the only reliable source here. It is deliberately BEST-EFFORT: any
+ * failure (outage, rate-limit) yields fewer or no dates, never a build failure.
+ * The changelog content always renders from CHANGELOG.md regardless.
+ */
+
+const REPO = 'inkeep/open-knowledge';
+const REPO_URL = `https://github.com/${REPO}`;
+const RELEASES_API = `https://api.github.com/repos/${REPO}/releases`;
+
+/** GitHub's max page size for the releases list. */
+const PER_PAGE = 100;
+
+/**
+ * Date enrichment covers the newest releases (the visible timeline). Betas
+ * dominate the feed, so a few pages comfortably reach ~30 stables; this bounds the
+ * best-effort call so it can never walk the whole feed.
+ */
+const MAX_DATE_PAGES = 5;
+
+/** How many of the newest stable releases to look up dates for. */
+const DATE_LIMIT = 30;
+
+/**
+ * Build-time path to the published CLI package's changelog. `process.cwd()` is the
+ * docs project root during `next build`/`next dev`; the changelog is one level up
+ * in the sibling `packages/cli`.
+ */
+const CHANGELOG_PATH = join(process.cwd(), '..', 'packages', 'cli', 'CHANGELOG.md');
+
+/** A stable release with its notes rendered to HTML — the changelog's item shape. */
+export interface ReleaseNote {
+ /** Git tag, e.g. `v0.30.0` — the stable version identity + URL slug. */
+ tag: string;
+ /** Display title (the tag). */
+ title: string;
+ /** ISO publish date, or null when the API didn't supply one for this release. */
+ publishedAt: string | null;
+ /** Release notes rendered from GFM markdown to HTML (empty string if none). */
+ bodyHtml: string;
+ /** Canonical GitHub release page for this tag. */
+ htmlUrl: string;
+}
+
+/** `## X.Y.Z` section heading — stable versions only (a `-beta.N` suffix won't match). */
+const VERSION_HEADING = /^## (\d+\.\d+\.\d+)\s*$/;
+
+/**
+ * Changeset prefixes each bullet with the source commit's short hash
+ * (`- 3c124b0: …`). Strip it so the rendered notes read like the GitHub release
+ * body. Anchored to the bullet marker so indented continuation lines are untouched.
+ */
+const HASH_PREFIX = /^(\s*[-*] )[0-9a-f]{6,40}: /gm;
+
+/** Release notes are trusted GFM authored by maintainers via changesets. */
+function renderNotes(markdown: string): string {
+ const body = markdown.trim();
+ if (!body) return '';
+ return marked.parse(body, { gfm: true, async: false });
+}
+
+/**
+ * Parse a changeset-generated CHANGELOG.md into releases, newest first (the file's
+ * own order). Pure and network-free — dates are injected — so the parsing rules
+ * are unit-testable in isolation. Content before the first `## X.Y.Z` heading (the
+ * `# @inkeep/open-knowledge` title) is ignored.
+ */
+export function parseChangelog(
+ markdown: string,
+ dates: Map<string, string> = new Map(),
+): ReleaseNote[] {
+ const releases: ReleaseNote[] = [];
+ let version: string | null = null;
+ let body: string[] = [];
+
+ const flush = () => {
+ if (version === null) return;
+ const tag = `v${version}`;
+ releases.push({
+ tag,
+ title: tag,
+ publishedAt: dates.get(tag) ?? null,
+ bodyHtml: renderNotes(body.join('\n').replace(HASH_PREFIX, '$1')),
+ htmlUrl: `${REPO_URL}/releases/tag/${tag}`,
+ });
+ };
+
+ for (const line of markdown.split('\n')) {
+ const heading = VERSION_HEADING.exec(line);
+ if (heading) {
+ flush();
+ version = heading[1];
+ body = [];
+ } else if (version !== null) {
+ body.push(line);
+ }
+ }
+ flush();
+ return releases;
+}
+
+/**
+ * Collect `vX.Y.Z` → published_at from one releases-API page into `dates` (stable,
+ * published releases only). Defensive against payload shape drift — a malformed
+ * entry is skipped, never thrown, since dates are best-effort.
+ */
+export function collectDates(payload: unknown, dates: Map<string, string>, limit: number): void {
+ if (!Array.isArray(payload)) return;
+ for (const entry of payload) {
+ if (dates.size >= limit) return;
+ if (!entry || typeof entry !== 'object') continue;
+ const rec = entry as Record<string, unknown>;
+ if (rec.draft || rec.prerelease) continue;
+ const tag = rec.tag_name;
+ const date = rec.published_at;
+ if (typeof tag === 'string' && typeof date === 'string' && !dates.has(tag)) {
+ dates.set(tag, date);
+ }
+ }
+}
+
+/**
+ * Best-effort map of `vX.Y.Z` → ISO publish date for the newest `limit` stable
+ * releases. Bounded to {@link MAX_DATE_PAGES} and fully degradable: any HTTP,
+ * network, or parse failure returns the dates collected so far (possibly none) —
+ * it never throws, so it can never fail the docs build. `fetchImpl` is injectable
+ * for tests.
+ */
+export async function fetchReleaseDates(
+ limit = DATE_LIMIT,
+ fetchImpl: typeof fetch = fetch,
+): Promise<Map<string, string>> {
+ const dates = new Map<string, string>();
+ const token = process.env.GITHUB_TOKEN;
+ const headers = {
+ accept: 'application/vnd.github+json',
+ // GitHub rejects requests without a User-Agent; undici sets none by default.
+ 'user-agent': 'openknowledge.ai changelog',
+ ...(token ? { authorization: `Bearer ${token}` } : {}),
+ };
+ try {
+ for (let page = 1; page <= MAX_DATE_PAGES && dates.size < limit; page++) {
+ const res = await fetchImpl(`${RELEASES_API}?per_page=${PER_PAGE}&page=${page}`, { headers });
+ if (!res.ok) break;
+ const payload = await res.json();
+ collectDates(payload, dates, limit);
+ // Short page = end of the feed; stop even if we have fewer than `limit`.
+ if (!Array.isArray(payload) || payload.length < PER_PAGE) break;
+ }
+ } catch (err) {
+ console.warn(
+ `[releases] date enrichment failed; building changelog without dates: ${
+ err instanceof Error ? err.message : String(err)
+ }`,
+ );
+ }
+ return dates;
+}
+
+/**
+ * Read the changelog file, or `null` when it's absent. Absence is expected in the
+ * public mirror (the copybara manifest excludes `packages/**​/CHANGELOG.md`) and in
+ * any standalone clone of the OSS repo — there the changelog degrades to empty
+ * rather than failing the build. The live docs deploy from agents-private always
+ * has the file. A non-ENOENT error (permissions, I/O) still throws.
+ */
+function readChangelog(): string | null {
+ try {
+ return readFileSync(CHANGELOG_PATH, 'utf8');
+ } catch (err) {
+ if (err && typeof err === 'object' && (err as { code?: string }).code === 'ENOENT') {
+ console.warn(
+ `[changelog] CHANGELOG.md not found at ${CHANGELOG_PATH}; building an empty changelog. ` +
+ 'Expected in the public mirror (CHANGELOG.md is not mirrored). In a real docs deploy this ' +
+ "means files outside the root aren't checked out — enable 'Include files outside the Root " +
+ "Directory' on the Vercel project.",
+ );
+ return null;
+ }
+ throw err;
+ }
+}
+
+/**
+ * Load stable releases from CHANGELOG.md with notes rendered to HTML, newest
+ * first. Content is read from the local file (fails the build only if the file is
+ * missing/empty); dates are best-effort from the API. `limit` caps the count
+ * (default: all) for callers that only want the newest N.
+ */
+export async function loadStableReleases(
+ limit = Number.POSITIVE_INFINITY,
+ deps: { fetchImpl?: typeof fetch } = {},
+): Promise<ReleaseNote[]> {
+ const markdown = readChangelog();
+ if (markdown === null) return []; // file absent (public mirror) — empty changelog
+ const dates = await fetchReleaseDates(DATE_LIMIT, deps.fetchImpl ?? fetch);
+ const releases = parseChangelog(markdown, dates);
+ if (releases.length === 0) {
+ // The file is present but has no `## X.Y.Z` sections — malformed, not the
+ // expected-absent case above. Fail loud so a broken file can't ship silently.
+ throw new Error(
+ `[changelog] CHANGELOG.md at ${CHANGELOG_PATH} has no \`## X.Y.Z\` sections — malformed or empty.`,
+ );
+ }
+ return Number.isFinite(limit) ? releases.slice(0, limit) : releases;
+}
diff --git a/docs/src/lib/site.ts b/docs/src/lib/site.ts
index 916c160bf..c5e1ee66e 100644
--- a/docs/src/lib/site.ts
+++ b/docs/src/lib/site.ts
@@ -28,6 +28,21 @@ export const TWITTER_HANDLE = '@OpenKnowledge';
*/
export const GITHUB_URL = 'https://github.com/inkeep/open-knowledge';
export const DISCORD_URL = 'https://discord.gg/VRKk2EaGHN';
+/**
+ * On-site changelog route (stable release notes), rendered inside the docs shell.
+ * Its RSS feed lives at `${CHANGELOG_ROUTE}/rss.xml`.
+ */
+export const CHANGELOG_ROUTE = '/docs/changelog';
+/**
+ * How many of the newest stable releases the changelog TIMELINE (and the RSS
+ * feed) shows. A display cap only: the per-release `/docs/changelog/<tag>` pages
+ * and the sitemap still enumerate EVERY stable release, so no release ever loses
+ * its own indexable URL — older ones just drop off the timeline rather than
+ * making it unbounded. The build fetch stays complete (see `releases.ts`).
+ */
+export const CHANGELOG_TIMELINE_LIMIT = 30;
+/** Re-exported so changelog surfaces link the releases page from one import. */
+export { RELEASES_PAGE_URL } from './download-links';
export const X_URL = `https://x.com/${TWITTER_HANDLE.slice(1)}`;
export const SITE_DESCRIPTION =
'Beautiful, AI-native markdown editor for humans and agents. Build knowledge bases, LLM wikis, and agent 2nd brains.';
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index ac2b75da3..453cb4c17 100644
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -229,6 +229,9 @@ importers:
lucide-react:
specifier: ^0.503.0
version: 0.503.0([email protected])
+ marked:
+ specifier: ^18.0.6
+ version: 18.0.7
mermaid:
specifier: ^11.12.3
version: 11.16.0
@@ -8827,6 +8830,11 @@ packages:
engines: {node: '>= 20'}
hasBin: true
+ resolution: {integrity: sha512-iDVQ5ldaiKXn6b2JroX5kgRfmwgqolW7NpaEzTl1k/2Zh1njIEN9yniyLV/mOvWwtsE8OGgkjsCYvijuPk1dtA==}
+ engines: {node: '>= 20'}
+ hasBin: true
+
resolution: {integrity: sha512-OkeDaAZ/bQCxeFAozM55PKcKU0yJMPGifLwV4Qgjitu+5MoAfSQN4lsLJeXZ1b8w0x+/Emda6MZgXS1jvsapng==}
engines: {node: '>=10'}
@@ -19323,6 +19331,8 @@ snapshots:
+
dependencies:
escape-string-regexp: 4.0.0