feat: docs parity round 3 (code, search, i18n, components)

plans/024-docs-template-parity.md

@@ -7,7 +7,7 @@
 - **Risk**: LOW
 - **Depends on**: none
 - **Category**: authoring | ui | accessibility
-- **Status**: IN PROGRESS. The first two rounds are done (PR #7, PR #8).
+- **Status**: IN PROGRESS. Rounds 1 to 3 are done (PR #7, PR #8, PR #9).
   The remaining gaps are ranked below.
 - **Planned at**: commit `3579993`, 2026-10-11
 
@@ -96,24 +96,41 @@ authoring components, which authors notice first when they migrate.
 - **Fix.** A single-line `<Callout>...</Callout>` in MDX now renders as a block
   callout.
 
+## Delivered in round 3 (PR #9)
+
+- **Collapsible callouts.** `:::details Title` in Markdown and MDX renders a
+  native `<details>` callout that starts closed.
+- **Code blocks.** `diff-<lang>` fences get syntax colours and +/- line
+  marking. Quoted terms (`"apiKey"`) are highlighted. `noLineNumbers` or
+  `showLineNumbers` sets line numbers per block, and a header button toggles
+  them. Added the Prism languages diff, python, yaml, sql, go, and rust.
+- **MDX parity.** Code blocks nested inside MDX callouts and tabs get the copy
+  button and syntax colours. `<Tabs group="key">` syncs with Markdown
+  `:::tabs key`.
+- **Steps and cards.** Markdown `:::steps` and `:::cards` (`::card
+[Title](/path)`). MDX `<Steps>`, `<CardGrid>`, and `<Card title href>`.
+  Card links accept only site paths and https URLs.
+- **Search.** Pagefind records carry section, collection, version, and locale
+  filters. Results stay in the reader's version and locale. `docs:` and
+  `api:` scope a query. Ranking is tuned and title matches are boosted.
+  **Fix:** the command palette never loaded Pagefind, because `pagefind.js` is
+  an ES module that does not set `window.pagefind`. It now imports the module.
+- **Translatable interface labels.** `uiStringsConfig` sets the labels for
+  each locale (`shared/uiStrings.js`). `generate:docs` validates it.
+
 ## Remaining gaps, in priority order
 
-1. **Code block polish.** Add diff fences with syntax highlighting
-   (`diff-ts`), word/inline highlighting, a per-block toggle for line numbers,
-   and collapsible callouts (`:::details`).
-2. **Search quality tuning.** Use Pagefind ranking weights, metadata filters
-   (collection, version, locale), and heading-level result anchors. Compare
-   results with Starlight defaults on the same corpus.
-3. **i18n UI strings.** Routing works, but check that the chrome labels
-   (sidebar, footer, palette) can be translated per locale.
-4. **Raster social cards.** The per-page cards are SVG, and some social
-   networks ignore SVG `og:image`. Rendering PNGs needs a rasterizer
-   dependency, which needs a dependency review first.
-5. **Tabs and code parity.** MDX `<Tabs>` do not sync by group yet. MDX code
-   blocks nested inside callouts or tabs stay static HTML. Markdown tabs cannot
-   be nested.
-6. **Low priority.** An RSS/Atom feed for changelog-style collections, and
-   Mintlify-style `Steps`/`Card` components.
+1. **Raster social cards.** The cards are still SVG. PNG output needs a
+   rasterizer dependency, which is not approved yet.
+2. **Heading-level search results.** Pagefind custom records have no
+   headings, so results link to whole pages. Indexing the route HTML would
+   give section anchors.
+3. **Search filter UI.** Scopes use a query prefix. There are no filter chips
+   in the palette yet.
+4. **More translatable labels.** Sidebar, mindmap, and palette command labels
+   are still English-only.
+5. **Nested Markdown tabs**, and a theme-aware diff palette per theme.
+6. **Low priority.** An RSS/Atom feed for changelog-style collections.
 
 ## Verification
 

public/collections.json

@@ -1,7 +1,7 @@
 {
   "contractVersion": 1,
   "schemaVersion": 1,
-  "generated": "2026-10-11T13:11:16.429Z",
+  "generated": "2026-10-11T16:01:47.501Z",
   "collections": [
     {
       "id": "docs",
@@ -15,7 +15,7 @@
         "references": "/docs-references.json"
       },
       "schemaVersion": 1,
-      "count": 32
+      "count": 34
     }
   ]
 }

public/docs-collection.json

@@ -11,8 +11,8 @@
     "manifest": "/docs-collection.json",
     "references": "/docs-references.json"
   },
-  "generated": "2026-10-11T13:11:16.429Z",
-  "count": 32,
+  "generated": "2026-10-11T16:01:47.501Z",
+  "count": 34,
   "schema": {
     "title": {
       "type": "string"
@@ -190,6 +190,18 @@
           "path": "developer-guides/callouts-in-mdx",
           "tags": ["callouts", "admonitions", "code", "mdx"]
         },
+        {
+          "type": "file",
+          "name": "Steps And Cards.md",
+          "path": "developer-guides/steps-and-cards",
+          "tags": ["steps", "cards", "components", "layout"]
+        },
+        {
+          "type": "file",
+          "name": "Translating The Interface.md",
+          "path": "developer-guides/translating-the-interface",
+          "tags": ["i18n", "locales", "labels", "translation"]
+        },
         {
           "type": "file",
           "name": "Math And Diagrams.md",
@@ -624,6 +636,25 @@
       },
       "sourcePath": "src/docs/content/developer-guides/math-in-mdx.mdx"
     },
+    {
+      "path": "developer-guides/steps-and-cards",
+      "title": "Steps And Cards",
+      "description": "Numbered steps and link cards for guides and landing pages.",
+      "frontmatter": {
+        "description": "Numbered steps and link cards for guides and landing pages."
+      },
+      "metadata": {
+        "title": "Steps And Cards",
+        "description": "Numbered steps and link cards for guides and landing pages.",
+        "canonicalPath": "/docs/developer-guides/steps-and-cards",
+        "contentFormat": "markdown",
+        "sourcePath": "src/docs/content/developer-guides/steps-and-cards.md",
+        "collection": "docs",
+        "routePrefix": "/docs",
+        "schemaVersion": 1
+      },
+      "sourcePath": "src/docs/content/developer-guides/steps-and-cards.md"
+    },
     {
       "path": "developer-guides/tailwind-integration",
       "title": "Tailwind Integration",
@@ -658,6 +689,25 @@
       },
       "sourcePath": "src/docs/content/developer-guides/themes.md"
     },
+    {
+      "path": "developer-guides/translating-the-interface",
+      "title": "Translating The Interface",
+      "description": "Translate or rename the labels in the docs chrome, per locale.",
+      "frontmatter": {
+        "description": "Translate or rename the labels in the docs chrome, per locale."
+      },
+      "metadata": {
+        "title": "Translating The Interface",
+        "description": "Translate or rename the labels in the docs chrome, per locale.",
+        "canonicalPath": "/docs/developer-guides/translating-the-interface",
+        "contentFormat": "markdown",
+        "sourcePath": "src/docs/content/developer-guides/translating-the-interface.md",
+        "collection": "docs",
+        "routePrefix": "/docs",
+        "schemaVersion": 1
+      },
+      "sourcePath": "src/docs/content/developer-guides/translating-the-interface.md"
+    },
     {
       "path": "developer-guides/ui-configuration",
       "title": "UI Configuration",

public/docs-content/developer-guides/callouts-and-code.json

@@ -5,7 +5,7 @@
   "frontmatter": {
     "description": "Callouts (admonitions), GitHub-style alerts, code block titles, line highlighting, and diffs."
   },
-  "content": "# Callouts And Code Blocks\n\nPapers Markdown supports callouts for asides and warnings, plus code fence\nmetadata for filenames, highlighted lines, and diffs. These features work in\n`.md` pages.\n\n## Callouts\n\nWrap content in `:::type` and close it with `:::`. The five types are `note`,\n`tip`, `info`, `warning`, and `danger`. Text after the type becomes the title.\n\n```md\n:::note\nCallouts can contain **Markdown**, lists, and code.\n:::\n\n:::warning Breaking change\n`generate:docs` now validates frontmatter.\n:::\n```\n\n:::note\nCallouts can contain **Markdown**, lists, and code.\n:::\n\n:::tip Faster previews\nRun `npm run dev` to regenerate artifacts and start Vite in one step.\n:::\n\n:::info\nSearch results come from the Pagefind index built with `npm run build`.\n:::\n\n:::warning Breaking change\n`generate:docs` now validates frontmatter.\n:::\n\n:::danger\nNever commit deployment credentials to `wrangler.toml`.\n:::\n\n### Nesting\n\nGive the outer fence more colons than the inner one:\n\n```md\n::::info Outer\nOuter text.\n\n:::tip Inner\nInner text.\n:::\n::::\n```\n\n::::info Outer\nOuter text.\n\n:::tip Inner\nInner text.\n:::\n::::\n\n## GitHub-Style Alerts\n\nThe GitHub alert syntax renders the same way, so READMEs and docs can share\ncontent. `IMPORTANT` uses the info style and `CAUTION` uses the danger style.\n\n```md\n> [!TIP]\n> Alerts written for GitHub render as callouts here too.\n```\n\n> [!TIP]\n> Alerts written for GitHub render as callouts here too.\n\n> [!CAUTION]\n> Deleting `dist/` removes the last build output.\n\n## Code Block Titles\n\nAdd `title=\"...\"` after the language to show a filename in the code block header.\n\n````md\n```ts title=\"src/greet.ts\"\nexport const greet = (name: string) => `Hello, ${name}`;\n```\n````\n\n```ts title=\"src/greet.ts\"\nexport const greet = (name: string) => `Hello, ${name}`;\n```\n\n## Line Highlighting\n\nList line numbers or ranges in braces. You can combine them with a title.\n\n````md\n```ts title=\"vite.config.ts\" {2,4-5}\nimport { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\n\nexport default defineConfig({\n  plugins: [react()],\n});\n```\n````\n\n```ts title=\"vite.config.ts\" {2,4-5}\nimport { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\n\nexport default defineConfig({\n  plugins: [react()],\n});\n```\n\n## Diffs\n\nA `diff` fence marks lines that start with `+` as added and lines that start\nwith `-` as removed. The `+` and `-` markers stay visible, so the change does\nnot depend on color alone.\n\n````md\n```diff title=\"package.json\"\n   \"scripts\": {\n-    \"build\": \"vite build\"\n+    \"build\": \"npm run generate:docs && vite build\"\n   }\n```\n````\n\n```diff title=\"package.json\"\n   \"scripts\": {\n-    \"build\": \"vite build\"\n+    \"build\": \"npm run generate:docs && vite build\"\n   }\n```\n\nEvery code block keeps its copy button. The copy button copies the code\nexactly as written, including diff markers.\n\n## Content Tabs\n\nWrap tabs in `:::tabs` and start each tab with a `::tab Label` line. Tabs can\nhold any Markdown, including code blocks.\n\nAdd a group key after `tabs` to keep tab sets in sync. Choosing a tab in one\nset switches every set with the same key on the page. The choice is saved in\nthe browser, so other pages open on the same tab.\n\n````md\n:::tabs pkg\n::tab npm\n\n```bash\nnpm install papers\n```\n\n::tab pnpm\n\n```bash\npnpm add papers\n```\n\n:::\n````\n\n:::tabs pkg\n::tab npm\n\n```bash\nnpm install papers\n```\n\n::tab pnpm\n\n```bash\npnpm add papers\n```\n\n:::\n\nThis second set uses the same `pkg` key, so it follows the first one:\n\n:::tabs pkg\n::tab npm\nRun `npm run dev` to start the dev server.\n::tab pnpm\nRun `pnpm dev` to start the dev server.\n:::\n\nTabs without a group key switch on their own. If a panel contains a callout,\ngive the tabs fence more colons than the callout, for example `::::tabs`.\nTabs cannot be nested.\n",
+  "content": "# Callouts And Code Blocks\n\nPapers Markdown supports callouts for asides and warnings, plus code fence\nmetadata for filenames, highlighted lines, and diffs. These features work in\n`.md` pages.\n\n## Callouts\n\nWrap content in `:::type` and close it with `:::`. The five types are `note`,\n`tip`, `info`, `warning`, and `danger`. Text after the type becomes the title.\n\n```md\n:::note\nCallouts can contain **Markdown**, lists, and code.\n:::\n\n:::warning Breaking change\n`generate:docs` now validates frontmatter.\n:::\n```\n\n:::note\nCallouts can contain **Markdown**, lists, and code.\n:::\n\n:::tip Faster previews\nRun `npm run dev` to regenerate artifacts and start Vite in one step.\n:::\n\n:::info\nSearch results come from the Pagefind index built with `npm run build`.\n:::\n\n:::warning Breaking change\n`generate:docs` now validates frontmatter.\n:::\n\n:::danger\nNever commit deployment credentials to `wrangler.toml`.\n:::\n\n### Nesting\n\nGive the outer fence more colons than the inner one:\n\n```md\n::::info Outer\nOuter text.\n\n:::tip Inner\nInner text.\n:::\n::::\n```\n\n::::info Outer\nOuter text.\n\n:::tip Inner\nInner text.\n:::\n::::\n\n### Collapsible Callouts\n\n`:::details Title` renders a callout that starts closed. Readers open it by\nclicking the title or pressing Enter or Space on it.\n\n```md\n:::details Show the full config\nThe full configuration lives in `shared/documentation-config.js`.\n:::\n```\n\n:::details Show the full config\nThe full configuration lives in `shared/documentation-config.js`.\n:::\n\n## GitHub-Style Alerts\n\nThe GitHub alert syntax renders the same way, so READMEs and docs can share\ncontent. `IMPORTANT` uses the info style and `CAUTION` uses the danger style.\n\n```md\n> [!TIP]\n> Alerts written for GitHub render as callouts here too.\n```\n\n> [!TIP]\n> Alerts written for GitHub render as callouts here too.\n\n> [!CAUTION]\n> Deleting `dist/` removes the last build output.\n\n## Code Block Titles\n\nAdd `title=\"...\"` after the language to show a filename in the code block header.\n\n````md\n```ts title=\"src/greet.ts\"\nexport const greet = (name: string) => `Hello, ${name}`;\n```\n````\n\n```ts title=\"src/greet.ts\"\nexport const greet = (name: string) => `Hello, ${name}`;\n```\n\n## Line Highlighting\n\nList line numbers or ranges in braces. You can combine them with a title.\n\n````md\n```ts title=\"vite.config.ts\" {2,4-5}\nimport { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\n\nexport default defineConfig({\n  plugins: [react()],\n});\n```\n````\n\n```ts title=\"vite.config.ts\" {2,4-5}\nimport { defineConfig } from 'vite';\nimport react from '@vitejs/plugin-react';\n\nexport default defineConfig({\n  plugins: [react()],\n});\n```\n\n## Diffs\n\nA `diff` fence marks lines that start with `+` as added and lines that start\nwith `-` as removed. The `+` and `-` markers stay visible, so the change does\nnot depend on color alone.\n\n````md\n```diff title=\"package.json\"\n   \"scripts\": {\n-    \"build\": \"vite build\"\n+    \"build\": \"npm run generate:docs && vite build\"\n   }\n```\n````\n\n```diff title=\"package.json\"\n   \"scripts\": {\n-    \"build\": \"vite build\"\n+    \"build\": \"npm run generate:docs && vite build\"\n   }\n```\n\nTo colour the code as well, add the language after `diff-`, for example\n`diff-ts` or `diff-json`:\n\n```diff-ts title=\"greet.ts\"\n export function greet(name: string) {\n-  return 'Hello ' + name;\n+  return `Hello, ${name}!`;\n }\n```\n\n## Word Highlighting\n\nPut a term in quotes after the language to highlight every place it appears.\nYou can list up to 10 terms.\n\n````md\n```ts \"apiKey\" \"fetchDocs\"\nconst apiKey = process.env.DOCS_API_KEY;\nawait fetchDocs({ apiKey });\n```\n````\n\n```ts \"apiKey\" \"fetchDocs\"\nconst apiKey = process.env.DOCS_API_KEY;\nawait fetchDocs({ apiKey });\n```\n\n## Line Numbers\n\nCode blocks show line numbers by default. Add `noLineNumbers` (or\n`showLineNumbers=false`) to hide them for one block. Readers can also show\nor hide line numbers with the button in any code block's header.\n\n````md\n```bash noLineNumbers\nnpm run build\n```\n````\n\n```bash noLineNumbers\nnpm run build\n```\n\nEvery code block keeps its copy button. The copy button copies the code\nexactly as written, including diff markers.\n\n## Content Tabs\n\nWrap tabs in `:::tabs` and start each tab with a `::tab Label` line. Tabs can\nhold any Markdown, including code blocks.\n\nAdd a group key after `tabs` to keep tab sets in sync. Choosing a tab in one\nset switches every set with the same key on the page. The choice is saved in\nthe browser, so other pages open on the same tab.\n\n````md\n:::tabs pkg\n::tab npm\n\n```bash\nnpm install papers\n```\n\n::tab pnpm\n\n```bash\npnpm add papers\n```\n\n:::\n````\n\n:::tabs pkg\n::tab npm\n\n```bash\nnpm install papers\n```\n\n::tab pnpm\n\n```bash\npnpm add papers\n```\n\n:::\n\nThis second set uses the same `pkg` key, so it follows the first one:\n\n:::tabs pkg\n::tab npm\nRun `npm run dev` to start the dev server.\n::tab pnpm\nRun `pnpm dev` to start the dev server.\n:::\n\nTabs without a group key switch on their own. If a panel contains a callout,\ngive the tabs fence more colons than the callout, for example `::::tabs`.\nTabs cannot be nested.\n",
   "contentFormat": "markdown",
   "toc": [
     {
@@ -23,6 +23,11 @@
       "id": "nesting",
       "text": "Nesting"
     },
+    {
+      "depth": 3,
+      "id": "collapsible-callouts",
+      "text": "Collapsible Callouts"
+    },
     {
       "depth": 2,
       "id": "github-style-alerts",
@@ -43,6 +48,16 @@
       "id": "diffs",
       "text": "Diffs"
     },
+    {
+      "depth": 2,
+      "id": "word-highlighting",
+      "text": "Word Highlighting"
+    },
+    {
+      "depth": 2,
+      "id": "line-numbers",
+      "text": "Line Numbers"
+    },
     {
       "depth": 2,
       "id": "content-tabs",