From acdf4cf0ffc689a1241c7261a5da06750f8a9b7e Mon Sep 17 00:00:00 2001
From: Charan <charanxmn@gmail.com>
Date: Tue, 27 Oct 2026 14:15:23 +0530
Subject: [PATCH] feat(astro): changelog ids per entry, authoring docs,
 optional credit line

The changelog page rendered every entry's MDX on its own, so two releases
with an "Added" section both had id="added" (and their footnotes collided the
same way). Heading and footnote ids inside an entry are now scoped to it
(#v0-2-0-added), with the links and ARIA references that point at them, and
entries whose files share a name get distinct anchors, the oldest keeping
the plain one. A version written as v1.2.0 no longer shows as vv1.2.0, and
the date is a <time> element.

The README documents how to write entries: file names, frontmatter, status,
anchors, grouping under ### headings. The format is the Next.js themes' own.

A new `credits` option adds a small "Built with Inkform" link to the
repository under each page, outside the search index. It's off by default,
like the integration's other additions to what readers see.

The example's changelog uses grouped sections, and it turns credits on; e2e
tests check both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_011YQ6fJxGHg3CxGkTzw6Yhc
---
 examples/astro-docs/README.md                 |  1 +
 examples/astro-docs/astro.config.ts           |  2 +
 .../content/changelog/2026-10-01-v0-0-1.mdx   |  2 +
 .../content/changelog/2026-10-23-v0-1-0.mdx   |  6 ++
 examples/astro-docs/e2e/docs.spec.ts          | 24 ++++++++
 packages/astro/CHANGELOG.md                   |  8 +++
 packages/astro/README.md                      | 51 ++++++++++++++++-
 packages/astro/src/components/Shell.astro     | 14 ++++-
 .../src/components/views/ChangelogPage.astro  | 26 +++++++--
 packages/astro/src/options.test.ts            |  7 ++-
 packages/astro/src/options.ts                 |  7 +++
 packages/astro/src/runtime/changelog.test.ts  | 57 +++++++++++++++++++
 packages/astro/src/runtime/changelog.ts       | 32 +++++++++++
 packages/astro/src/runtime/headings.ts        | 36 ++++++++++++
 packages/astro/src/styles/astro.css           | 20 +++++++
 15 files changed, 284 insertions(+), 9 deletions(-)
 create mode 100644 packages/astro/src/runtime/changelog.test.ts
 create mode 100644 packages/astro/src/runtime/changelog.ts

diff --git a/examples/astro-docs/README.md b/examples/astro-docs/README.md
index 73d3be8..81511e0 100644
--- a/examples/astro-docs/README.md
+++ b/examples/astro-docs/README.md
@@ -21,6 +21,7 @@ npm run test:e2e --workspace=@inkform/example-astro-docs   # Playwright: builds,
 - [`src/mdx-components.tsx`](./src/mdx-components.tsx) is the site's own MDX
   component (`<Screenshot>`), registered with the `components` option and
   styled by `src/styles/docs.css` through `customCss`.
+- `credits: true` turns on the "Built with Inkform" line under each page.
 - [`e2e/docs.spec.ts`](./e2e/docs.spec.ts) checks that every page renders with
   no CSP violation, that tabs, code groups, accordions, the TOC, the theme
   toggle, the drawer, diagrams, the API sample pickers and Try It work, that
diff --git a/examples/astro-docs/astro.config.ts b/examples/astro-docs/astro.config.ts
index 4227497..eba3f8a 100644
--- a/examples/astro-docs/astro.config.ts
+++ b/examples/astro-docs/astro.config.ts
@@ -18,6 +18,8 @@ export default defineConfig({
       // The site's own MDX components, and the CSS they use.
       components: './src/mdx-components.tsx',
       customCss: ['./src/styles/docs.css'],
+      // "Built with Inkform" under each page. Off unless a site turns it on.
+      credits: true,
     }),
   ],
   // This site has no Markdown pages of its own. Docs code blocks are
diff --git a/examples/astro-docs/content/changelog/2026-10-01-v0-0-1.mdx b/examples/astro-docs/content/changelog/2026-10-01-v0-0-1.mdx
index 581b33f..3d01b64 100644
--- a/examples/astro-docs/content/changelog/2026-10-01-v0-0-1.mdx
+++ b/examples/astro-docs/content/changelog/2026-10-01-v0-0-1.mdx
@@ -4,6 +4,8 @@ date: 2026-10-01
 version: 0.0.1
 ---
 
+### Added
+
 A route per `docs.json` page.
 
 ```ts
diff --git a/examples/astro-docs/content/changelog/2026-10-23-v0-1-0.mdx b/examples/astro-docs/content/changelog/2026-10-23-v0-1-0.mdx
index bb0f100..4d8a953 100644
--- a/examples/astro-docs/content/changelog/2026-10-23-v0-1-0.mdx
+++ b/examples/astro-docs/content/changelog/2026-10-23-v0-1-0.mdx
@@ -4,6 +4,12 @@ date: 2026-10-23
 version: 0.1.0
 ---
 
+### Added
+
 - Docs pages, the API Reference, blog and changelog under one base path.
 - Pagefind search, built after `astro build`.
 - `llms.txt` and `llms-full.txt`.
+
+### Changed
+
+- Rendered without React in the browser: tabs, code groups and search are small scripts.
diff --git a/examples/astro-docs/e2e/docs.spec.ts b/examples/astro-docs/e2e/docs.spec.ts
index 82a67b2..fc797fd 100644
--- a/examples/astro-docs/e2e/docs.spec.ts
+++ b/examples/astro-docs/e2e/docs.spec.ts
@@ -237,6 +237,30 @@ test.describe('components', () => {
   });
 });
 
+test.describe('changelog', () => {
+  test('lists each version with its date, and every id on the page is unique', async ({ page }) => {
+    await page.goto('/docs/changelog');
+    await expect(page.locator('.fw-changelog-title')).toHaveText(['The Astro integration', 'First sketch']);
+    await expect(page.locator('.fw-changelog-entry .fw-page-meta')).toHaveText(['2026-10-23 · v0.1.0', '2026-10-01 · v0.0.1']);
+    await expect(page.locator('.fw-toc-link')).toHaveText(['The Astro integration', 'First sketch']);
+    await expect(page.locator('.fw-toc-link').first()).toHaveAttribute('href', '#v0-1-0');
+    // Both entries have an "Added" section; each keeps its own id.
+    await expect(page.locator('#v0-1-0-added')).toHaveText('Added');
+    await expect(page.locator('#v0-0-1-added')).toHaveText('Added');
+    const ids = await page.locator('[id]').evaluateAll((els) => els.map((el) => el.id));
+    expect(ids.filter((id, i) => ids.indexOf(id) !== i)).toEqual([]);
+  });
+});
+
+test.describe('credits', () => {
+  test('the "Built with Inkform" line links to the repository and stays out of search', async ({ page }) => {
+    await page.goto('/docs/quickstart');
+    const credit = page.locator('main .fw-credits');
+    await expect(credit.getByRole('link', { name: 'Built with Inkform' })).toHaveAttribute('href', 'https://github.com/inkform-dev/framework');
+    await expect(credit).toHaveAttribute('data-pagefind-ignore', 'all');
+  });
+});
+
 test.describe('API reference', () => {
   test('the sample picker and response tabs switch', async ({ page }) => {
     await page.goto('/docs/api-reference/operations/create-plant');
diff --git a/packages/astro/CHANGELOG.md b/packages/astro/CHANGELOG.md
index e20f507..d325c79 100644
--- a/packages/astro/CHANGELOG.md
+++ b/packages/astro/CHANGELOG.md
@@ -7,6 +7,11 @@ Versions track `packages/astro/package.json`. Format loosely follows
 
 ### Fixed
 
+- Headings inside changelog entries no longer share ids across entries: each
+  entry's heading and footnote ids are scoped to it (`#v0-2-0-added`), and
+  two entries whose files share a name get distinct anchors. A `version`
+  written with its `v` (`v1.2.0`) no longer shows as `vv1.2.0`, and the date
+  is a `<time>` element.
 - Every link the integration prints respects Astro's `base`. Site-root links
   in docs.json (`navbarLinks`, `anchors`, `cta`, sidebar entries with an
   `href`) and in MDX that aren't docs pages (`/`, `/pricing`) get the base in
@@ -32,6 +37,9 @@ Versions track `packages/astro/package.json`. Format loosely follows
   kit name it reuses replaces the kit's component. A `.tsx`/`.jsx` module
   works in a site without `@astrojs/react`: the integration has Vite compile
   its JSX for React when no UI integration does.
+- `credits` option: a small "Built with Inkform" link to the Inkform repository
+  under every docs page. Off by default.
+- README: how to write changelog entries (file names, frontmatter, anchors).
 - `--fw-label-transform`, `--fw-label-letter-spacing` and
   `--fw-label-font-size` set the case, tracking and size of the sidebar's
   group names and the "On this page" title, which stay small uppercase by
diff --git a/packages/astro/README.md b/packages/astro/README.md
index 5b8f7a5..7499c20 100644
--- a/packages/astro/README.md
+++ b/packages/astro/README.md
@@ -17,7 +17,7 @@ the browser gets plain HTML and a few small scripts, and no React.
 | `<base>` and `<base>/<slug>` | Every page listed in `content/docs/docs.json` |
 | `<base>/<api-tab>` and `<base>/<api-tab>/operations/<operationId>` | The API Reference, when a docs.json tab has `openapi` (`<api-tab>` is the tab's label, slugified: `api-reference`) |
 | `<base>/blog`, `<base>/blog/<slug>` | When `content/blog/` has published posts |
-| `<base>/changelog` | When `content/changelog/` has entries |
+| `<base>/changelog` | When `content/changelog/` has entries (see [Changelog](#changelog)) |
 | `<base>/llms.txt`, `<base>/llms-full.txt` | The [llms.txt](https://llmstxt.org) index (its links match the pages', `base` and trailing slash included) and the full corpus |
 | `<base>/_pagefind/` | The search index, written after `astro build` |
 
@@ -81,6 +81,7 @@ content/
 | `search` | `true` | Build a Pagefind index after `astro build` and show the search dialog. |
 | `mermaid` | `false` | Draw ```` ```mermaid ```` fences as diagrams in the browser. Needs `npm install mermaid`. Off, they show their source. |
 | `llmsTxt` | `true` | Serve `llms.txt` and `llms-full.txt`. |
+| `credits` | `false` | Show a small "Built with Inkform" link, to the [Inkform repository](https://github.com/inkform-dev/framework), under every docs page. |
 
 ## Components
 
@@ -152,6 +153,54 @@ theme is (`[Quickstart](/quickstart)`), get the docs base added when they point
 at a docs page. See [Astro's `base` and `trailingSlash`](#astros-base-and-trailingslash)
 for the rest.
 
+## Changelog
+
+`content/changelog/` turns on `<base>/changelog`: one page with every entry,
+newest first, each under its date and version, and the entries listed in the
+on-this-page rail. Write one MDX file per release, named
+`YYYY-MM-DD-<slug>.mdx`:
+
+```
+content/changelog/
+  2026-10-23-v0-2-0.mdx
+  2026-09-02-v0-1-0.mdx
+```
+
+```mdx
+---
+title: Faster search
+date: 2026-10-23
+version: 0.2.0
+---
+
+### Added
+
+- Results highlight the words you searched for.
+
+### Fixed
+
+- Links under a base path.
+```
+
+| Frontmatter | What |
+| --- | --- |
+| `title` | The entry's heading. |
+| `date` | `YYYY-MM-DD`. Entries are sorted by it, newest first, and it's shown above the title. |
+| `version` | Optional. Shown after the date as `v0.2.0`; a `v` you write isn't doubled. |
+| `status` | Optional. `published` (the default); `draft` leaves the entry out; `scheduled` leaves it out of builds before its `date`. |
+| `tags` | Optional. Read by the framework's loader, not shown. |
+
+- The file name without its date is the entry's anchor:
+  `<base>/changelog#v0-2-0`. When two files share a name, the oldest entry
+  keeps it and newer ones get `-2`, `-3`.
+- Group changes under `###` headings (Added, Changed, Fixed). Their ids are
+  scoped to the entry (`#v0-2-0-fixed`), so every release can use the same
+  headings.
+- The body is MDX, with the kit's components and your own.
+- The header gets a Changelog link, `llms.txt` links the page, `llms-full.txt`
+  includes every entry, and search finds entries under the Changelog filter.
+- The folder and format are the same as the Next.js themes' `/changelog`.
+
 ## Astro's `base` and `trailingSlash`
 
 Write links from the site root, as if the site were served from `/`, and the
diff --git a/packages/astro/src/components/Shell.astro b/packages/astro/src/components/Shell.astro
index 21dd146..254c1be 100644
--- a/packages/astro/src/components/Shell.astro
+++ b/packages/astro/src/components/Shell.astro
@@ -1,7 +1,8 @@
 ---
 /**
  * The three-zone docs shell: header (logo, tabs, search, theme toggle, CTA),
- * sidebar, article, on-this-page rail. Same markup and `fw-shell*` classes as
+ * sidebar, article, on-this-page rail, and the "Built with Inkform" line
+ * under the article when the `credits` option is on. Same markup and `fw-shell*` classes as
  * the framework's DocsShell, so @inkform/framework/styles.css and theme
  * tokens style it unchanged. The mobile drawer, TOC highlight and theme
  * toggle are wired up by ../client/shell.ts.
@@ -41,6 +42,8 @@ const hasSidebar = !!sidebar && sidebar.length > 0;
 const hasToc = !!toc && toc.length > 0;
 const showMenu = hasSidebar || links.length > 0 || !!cta;
 const TYPE_LABEL = { doc: 'Docs', api: 'API', changelog: 'Changelog', blog: 'Blog' } as const;
+// Where the `credits` link goes: the open-source repository this package lives in.
+const INKFORM_URL = 'https://github.com/inkform-dev/framework';
 ---
 
 <div class:list={['fw-shell', !hasSidebar && 'fw-shell--no-sidebar', !hasToc && 'fw-shell--no-toc']}>
@@ -115,6 +118,15 @@ const TYPE_LABEL = { doc: 'Docs', api: 'API', changelog: 'Changelog', blog: 'Blo
     <main class="fw-shell-main" id="main-content" data-pagefind-body data-pagefind-filter={`type:${TYPE_LABEL[contentType]}`}>
       <div class="fw-shell-content">
         <slot />
+        {
+          config.credits ? (
+            <footer class="fw-credits" data-pagefind-ignore="all">
+              <a class="fw-credits-link" href={INKFORM_URL}>
+                Built with Inkform
+              </a>
+            </footer>
+          ) : null
+        }
       </div>
     </main>
 
diff --git a/packages/astro/src/components/views/ChangelogPage.astro b/packages/astro/src/components/views/ChangelogPage.astro
index 87227c4..c18d6fe 100644
--- a/packages/astro/src/components/views/ChangelogPage.astro
+++ b/packages/astro/src/components/views/ChangelogPage.astro
@@ -1,8 +1,14 @@
 ---
-/** Every changelog entry, newest first, each with an anchor (`#<slug>`). */
+/**
+ * Every changelog entry, newest first, each with an anchor (`#<slug>`). The
+ * headings inside an entry get ids scoped to it (`#<slug>-added`), so two
+ * releases with an "Added" section don't share an id.
+ */
 import Layout from '../Layout.astro';
 import PageHeader from '../PageHeader.astro';
 import Prose from '../Prose.astro';
+import { changelogAnchors, versionLabel } from '../../runtime/changelog';
+import { scopeIds } from '../../runtime/headings';
 import type { Site } from '../../runtime/site';
 
 export interface Props {
@@ -11,10 +17,14 @@ export interface Props {
 
 const { site } = Astro.props;
 const renderer = site.renderer();
+const anchors = changelogAnchors(site.changelog.map((e) => e.slug));
 const entries = await Promise.all(
-  site.changelog.map(async (entry) => ({ entry, html: await renderer.mdx(entry.content) })),
+  site.changelog.map(async (entry, i) => {
+    const anchor = anchors[i] ?? entry.slug;
+    return { entry, anchor, version: versionLabel(entry.version), html: scopeIds(await renderer.mdx(entry.content), anchor) };
+  }),
 );
-const toc = site.changelog.map((e) => ({ depth: 2, text: e.title, slug: e.slug }));
+const toc = entries.map(({ entry, anchor }) => ({ depth: 2, text: entry.title, slug: anchor }));
 ---
 
 <Layout
@@ -29,10 +39,14 @@ const toc = site.changelog.map((e) => ({ depth: 2, text: e.title, slug: e.slug }
 >
   <PageHeader title="Changelog" />
   {
-    entries.map(({ entry, html }) => (
+    entries.map(({ entry, anchor, version, html }) => (
       <article class="fw-changelog-entry">
-        <p class="fw-page-meta">{[entry.date, entry.version ? `v${entry.version}` : null].filter(Boolean).join(' · ')}</p>
-        <h2 class="fw-changelog-title" id={entry.slug}>
+        <p class="fw-page-meta">
+          {entry.date ? <time datetime={entry.date}>{entry.date}</time> : null}
+          {entry.date && version ? ' · ' : null}
+          {version ? <span class="fw-changelog-version">{version}</span> : null}
+        </p>
+        <h2 class="fw-changelog-title" id={anchor}>
           {entry.title}
         </h2>
         <Prose html={html} />
diff --git a/packages/astro/src/options.test.ts b/packages/astro/src/options.test.ts
index e590c7a..54bf1a7 100644
--- a/packages/astro/src/options.test.ts
+++ b/packages/astro/src/options.test.ts
@@ -24,7 +24,7 @@ describe('normalizeBase', () => {
 });
 
 describe('resolveOptions', () => {
-  it('defaults to /docs, ./content, galley, search on, mermaid off', () => {
+  it('defaults to /docs, ./content, galley, search on, mermaid and credits off', () => {
     const r = resolveOptions({}, host);
     expect(r).toMatchObject({
       base: '/docs',
@@ -36,6 +36,7 @@ describe('resolveOptions', () => {
       search: true,
       mermaid: false,
       llmsTxt: true,
+      credits: false,
       csp: false,
       cspAlgorithm: 'SHA-256',
     });
@@ -63,6 +64,10 @@ describe('resolveOptions', () => {
     expect(resolveOptions({ components: './src/mdx-components.tsx' }, host).components).toBe(path.resolve('/site', 'src/mdx-components.tsx'));
   });
 
+  it('shows the credit only when asked', () => {
+    expect(resolveOptions({ credits: true }, host).credits).toBe(true);
+  });
+
   it('keeps built-in theme names', () => {
     expect(resolveOptions({ theme: 'plain' }, host).theme).toBe('plain');
   });
diff --git a/packages/astro/src/options.ts b/packages/astro/src/options.ts
index 4dc7fc4..b2b244a 100644
--- a/packages/astro/src/options.ts
+++ b/packages/astro/src/options.ts
@@ -53,6 +53,11 @@ export interface InkformOptions {
   mermaid?: boolean;
   /** Serve `<base>/llms.txt` and `<base>/llms-full.txt`. Default `true`. */
   llmsTxt?: boolean;
+  /**
+   * Show a small "Built with Inkform" link, to the Inkform repository, at the
+   * foot of every docs page. Default `false`.
+   */
+  credits?: boolean;
 }
 
 /** Facts about the host's Astro config that the options resolve against. */
@@ -91,6 +96,7 @@ export interface ResolvedOptions {
   search: boolean;
   mermaid: boolean;
   llmsTxt: boolean;
+  credits: boolean;
   trailingSlash: HostConfig['trailingSlash'];
   csp: boolean;
   cspAlgorithm: CspAlgorithm;
@@ -136,6 +142,7 @@ export function resolveOptions(options: InkformOptions, host: HostConfig): Resol
     search: options.search ?? true,
     mermaid: options.mermaid ?? false,
     llmsTxt: options.llmsTxt ?? true,
+    credits: options.credits ?? false,
     trailingSlash: host.trailingSlash,
     csp: host.csp,
     cspAlgorithm: host.cspAlgorithm ?? 'SHA-256',
diff --git a/packages/astro/src/runtime/changelog.test.ts b/packages/astro/src/runtime/changelog.test.ts
new file mode 100644
index 0000000..d634aac
--- /dev/null
+++ b/packages/astro/src/runtime/changelog.test.ts
@@ -0,0 +1,57 @@
+import { describe, expect, it } from 'vitest';
+import { changelogAnchors, versionLabel } from './changelog';
+import { headingsFromHtml, scopeIds } from './headings';
+import { PageRenderer } from './render';
+
+describe('changelogAnchors', () => {
+  it('uses each entry’s slug', () => {
+    expect(changelogAnchors(['v0-2-0', 'v0-1-0'])).toEqual(['v0-2-0', 'v0-1-0']);
+  });
+
+  it('keeps the oldest entry’s anchor when slugs repeat, so newer entries never take it', () => {
+    // Newest first, as the loader returns them.
+    expect(changelogAnchors(['update', 'release', 'update', 'update'])).toEqual(['update-3', 'release', 'update-2', 'update']);
+    expect(changelogAnchors(['update', 'update-2', 'update'])).toEqual(['update-3', 'update-2', 'update']);
+    expect(changelogAnchors([''])).toEqual(['entry']);
+  });
+});
+
+describe('versionLabel', () => {
+  it('prints one v in front of a version number', () => {
+    expect(versionLabel('1.2.0')).toBe('v1.2.0');
+    expect(versionLabel('v1.2.0')).toBe('v1.2.0');
+    expect(versionLabel('V2')).toBe('v2');
+  });
+
+  it('shows anything else as written, and nothing for no version', () => {
+    expect(versionLabel('Spring 2026')).toBe('Spring 2026');
+    expect(versionLabel(null)).toBeNull();
+    expect(versionLabel('  ')).toBeNull();
+  });
+});
+
+describe('scopeIds', () => {
+  const renderer = () => new PageRenderer({ mermaid: false, operation: null });
+  const entry = '### Added\n\n- A thing[^1]\n\n### Fixed\n\n- See [Added](#added)\n\n[^1]: A note.\n';
+
+  it('gives two entries’ headings and footnotes their own ids, and keeps links to them working', async () => {
+    const r = renderer();
+    const a = scopeIds(await r.mdx(entry), 'v0-2-0');
+    const b = scopeIds(await r.mdx(entry), 'v0-1-0');
+    // GFM's footnote section has its own (visually hidden) heading.
+    expect(headingsFromHtml(a).map((h) => h.slug)).toEqual(['v0-2-0-added', 'v0-2-0-fixed', 'v0-2-0-footnote-label']);
+    expect(headingsFromHtml(b).map((h) => h.slug)).toEqual(['v0-1-0-added', 'v0-1-0-fixed', 'v0-1-0-footnote-label']);
+    expect(a).toMatch(/aria-describedby="v0-2-0-footnote-label"/);
+    expect(a).toContain('href="#v0-2-0-added"');
+
+    const ids = (html: string) => [...html.matchAll(/\sid="([^"]+)"/g)].map((m) => m[1]);
+    const shared = ids(a).filter((id) => ids(b).includes(id));
+    expect(shared).toEqual([]);
+    // Every in-page link in an entry lands on an id in that entry.
+    for (const [, target] of a.matchAll(/href="#([^"]+)"/g)) expect(ids(a)).toContain(target);
+  });
+
+  it('returns HTML without headings or footnotes unchanged', () => {
+    expect(scopeIds('<p>Plain <a href="#elsewhere">link</a></p>', 'x')).toBe('<p>Plain <a href="#elsewhere">link</a></p>');
+  });
+});
diff --git a/packages/astro/src/runtime/changelog.ts b/packages/astro/src/runtime/changelog.ts
new file mode 100644
index 0000000..a3f5549
--- /dev/null
+++ b/packages/astro/src/runtime/changelog.ts
@@ -0,0 +1,32 @@
+/**
+ * What the changelog page needs beyond the framework's loader: an anchor per
+ * entry that stays unique and stable, and the version label. Pure, so it's
+ * unit-tested.
+ */
+
+/**
+ * One anchor per entry, from its slug (the file name without the date
+ * prefix). `entries` are newest first, as the loader returns them. When two
+ * entries share a slug (`2026-01-05-update.mdx`, `2026-02-09-update.mdx`),
+ * the oldest keeps the plain slug and later ones get `-2`, `-3`, so a link to
+ * an entry doesn't move to another one when a newer entry is added.
+ */
+export function changelogAnchors(slugs: readonly string[]): string[] {
+  const used = new Set<string>();
+  const out = new Array<string>(slugs.length);
+  for (let i = slugs.length - 1; i >= 0; i--) {
+    const slug = slugs[i] || 'entry';
+    let anchor = slug;
+    for (let n = 2; used.has(anchor); n++) anchor = `${slug}-${n}`;
+    used.add(anchor);
+    out[i] = anchor;
+  }
+  return out;
+}
+
+/** `1.2.0` and `v1.2.0` → `v1.2.0`; anything that isn't a version number is shown as written. */
+export function versionLabel(version: string | null): string | null {
+  const v = version?.trim();
+  if (!v) return null;
+  return /^v?\d/i.test(v) ? `v${v.replace(/^v/i, '')}` : v;
+}
diff --git a/packages/astro/src/runtime/headings.ts b/packages/astro/src/runtime/headings.ts
index 78ca35c..c8eb69e 100644
--- a/packages/astro/src/runtime/headings.ts
+++ b/packages/astro/src/runtime/headings.ts
@@ -5,6 +5,7 @@
  */
 
 import { fromHtml } from 'hast-util-from-html';
+import { toHtml } from 'hast-util-to-html';
 import type { Element, ElementContent, Root } from 'hast';
 import { visit } from 'unist-util-visit';
 
@@ -38,3 +39,38 @@ export function headingsFromHtml(html: string, minDepth = 2, maxDepth = 3): TocH
   });
   return out;
 }
+
+/** Attributes that point at an id: a space-separated list of ids. */
+const ID_LISTS = ['ariaDescribedBy', 'ariaLabelledBy'] as const;
+
+/**
+ * Puts `prefix-` in front of the heading ids (and GFM footnote ids) in one
+ * rendered fragment, and in the links and ARIA references that point at
+ * them. For pages that render several MDX bodies, like the changelog: each
+ * body gets its ids from rehype-slug on its own, so two entries with an
+ * "Added" section would both have `id="added"`.
+ */
+export function scopeIds(html: string, prefix: string): string {
+  const tree = fromHtml(html, { fragment: true }) as Root;
+  const renamed = new Map<string, string>();
+  visit(tree, 'element', (node: Element) => {
+    const id = node.properties?.id;
+    if (typeof id !== 'string' || !id) return;
+    if (/^h[1-6]$/.test(node.tagName) || id.startsWith('user-content-')) renamed.set(id, `${prefix}-${id}`);
+  });
+  if (renamed.size === 0) return html;
+  visit(tree, 'element', (node: Element) => {
+    const props = node.properties ?? {};
+    if (typeof props.id === 'string' && renamed.has(props.id)) props.id = renamed.get(props.id);
+    if (typeof props.href === 'string' && props.href.startsWith('#')) {
+      const target = renamed.get(decodeURIComponent(props.href.slice(1)));
+      if (target) props.href = `#${target}`;
+    }
+    for (const attr of ID_LISTS) {
+      // hast parses these space-separated attributes into arrays.
+      const value: unknown = props[attr];
+      if (Array.isArray(value)) props[attr] = value.map((v) => renamed.get(String(v)) ?? String(v));
+    }
+  });
+  return toHtml(tree);
+}
diff --git a/packages/astro/src/styles/astro.css b/packages/astro/src/styles/astro.css
index 65e919f..80819a6 100644
--- a/packages/astro/src/styles/astro.css
+++ b/packages/astro/src/styles/astro.css
@@ -243,3 +243,23 @@ html:not(.dark) .fw-shell-brand-logo--dark {
   line-height: 1.3;
   scroll-margin-top: calc(var(--fw-header-h) + 1rem);
 }
+
+/* ── "Built with Inkform" (the `credits` option) ──────────────────────── */
+
+.fw-credits {
+  margin-top: var(--fw-space-8);
+  padding-top: var(--fw-space-4);
+  border-top: 1px solid var(--fw-border);
+  font-size: 0.8125rem;
+}
+
+.fw-credits-link {
+  color: var(--fw-muted);
+  text-decoration: none;
+}
+
+.fw-credits-link:hover {
+  color: var(--fw-fg);
+  text-decoration: underline;
+  text-underline-offset: 0.2em;
+}