Beautiful, AI-native markdown IDE and LLM wiki
TypeScript 2nd-brainagent-skillsclaudecodexcompany-braindocsknowledge-knowledge-baseknowledge-managementllmllm-wikillm-wiki-karpathymarkdownmarkdown-editormdmdxnotespkmsecond-brainskills
docs changelog (#2645)
shagun-singh-inkeepa1eac2e42e4f
diff --git a/.github/workflows/desktop-release.yml b/.github/workflows/desktop-release.ymlindex 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.jsonindex 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.jsonindex 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.tsxnew file mode 100644index 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.tsxnew file mode 100644index 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.tsnew file mode 100644index 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, '&')+ .replace(/</g, '<')+ .replace(/>/g, '>')+ .replace(/"/g, '"')+ .replace(/'/g, ''');+}++/**+ * 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.tsindex 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.tsxnew file mode 100644index 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.tsxindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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.tsindex 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.yamlindex ac2b75da3..453cb4c17 100644--- a/pnpm-lock.yaml+++ b/pnpm-lock.yaml@@ -229,6 +229,9 @@ importers:lucide-react:specifier: ^0.503.0version: 0.503.0([email protected])+ marked:+ specifier: ^18.0.6+ version: 18.0.7mermaid:specifier: ^11.12.3version: 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:+ [email protected]: {}+dependencies:escape-string-regexp: 4.0.0