@umami/shiso 0.61.0 → 1.1.0

package/CHANGELOG.md

@@ -3,6 +3,33 @@
 All notable changes to `@umami/shiso` are documented here. This project follows
 [Semantic Versioning](https://semver.org/).
 
+## 1.0.0 - 2026-08-15
+
+### Added
+
+- Full multi-version and multi-language navigation, including versions nested
+  inside languages and responsive header selectors.
+- Per-scope prerendering, Markdown export, sitemap metadata, document locale,
+  text direction, and local search results.
+- A multi-scope integration fixture covering visible and hidden pages,
+  versions, languages, redirects, search, and sitemap output.
+- Public exports for the bundled `docs.json` schema.
+
+### Changed
+
+- Navigation containers now require exactly one non-empty navigation mode, and
+  default to the first visible version or language when none is marked.
+- Hidden versions and languages remain buildable and directly reachable while
+  staying out of selectors and search.
+- Redirect sources are exact paths; wildcard and parameter patterns are
+  rejected during configuration validation.
+- Supported Node.js versions now match Vite: `^20.19.0 || >=22.12.0`.
+
+### Fixed
+
+- Client-side navigation now updates page metadata, document language, and
+  left-to-right or right-to-left text direction.
+
 ## 0.61.0 - 2026-08-13
 
 ### Added

package/docs.schema.json

@@ -104,6 +104,33 @@
     "navigation": {
       "type": "object",
       "description": "Site navigation. Define exactly one of: tabs, dropdowns, versions, languages, or top-level groups/pages.",
+      "anyOf": [
+        { "required": ["$ref"] },
+        { "required": ["tabs"] },
+        { "required": ["dropdowns"] },
+        { "required": ["versions"] },
+        { "required": ["languages"] },
+        { "required": ["groups"] },
+        { "required": ["pages"] }
+      ],
+      "not": {
+        "anyOf": [
+          { "required": ["tabs", "dropdowns"] },
+          { "required": ["tabs", "versions"] },
+          { "required": ["tabs", "languages"] },
+          { "required": ["tabs", "groups"] },
+          { "required": ["tabs", "pages"] },
+          { "required": ["dropdowns", "versions"] },
+          { "required": ["dropdowns", "languages"] },
+          { "required": ["dropdowns", "groups"] },
+          { "required": ["dropdowns", "pages"] },
+          { "required": ["versions", "languages"] },
+          { "required": ["versions", "groups"] },
+          { "required": ["versions", "pages"] },
+          { "required": ["languages", "groups"] },
+          { "required": ["languages", "pages"] }
+        ]
+      },
       "additionalProperties": false,
       "properties": {
         "$ref": { "$ref": "#/definitions/configRef" },
@@ -599,31 +626,31 @@
     },
     "redirectSourceValue": {
       "anyOf": [
-        { "type": "string", "pattern": "^/[^*]*$" },
+        { "type": "string", "pattern": "^/[^*:]*$" },
         { "$ref": "#/definitions/configRefValue" }
       ]
     },
     "pageItemList": {
       "anyOf": [
-        { "type": "array", "items": { "$ref": "#/definitions/pageItem" } },
+        { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/pageItem" } },
         { "$ref": "#/definitions/configRefValue" }
       ]
     },
     "groupList": {
       "anyOf": [
-        { "type": "array", "items": { "$ref": "#/definitions/group" } },
+        { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/group" } },
         { "$ref": "#/definitions/configRefValue" }
       ]
     },
     "dropdownList": {
       "anyOf": [
-        { "type": "array", "items": { "$ref": "#/definitions/dropdown" } },
+        { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/dropdown" } },
         { "$ref": "#/definitions/configRefValue" }
       ]
     },
     "tabList": {
       "anyOf": [
-        { "type": "array", "items": { "$ref": "#/definitions/tab" } },
+        { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/tab" } },
         { "$ref": "#/definitions/configRefValue" }
       ]
     },
@@ -635,13 +662,13 @@
     },
     "versionList": {
       "anyOf": [
-        { "type": "array", "items": { "$ref": "#/definitions/version" } },
+        { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/version" } },
         { "$ref": "#/definitions/configRefValue" }
       ]
     },
     "languageList": {
       "anyOf": [
-        { "type": "array", "items": { "$ref": "#/definitions/language" } },
+        { "type": "array", "minItems": 1, "items": { "$ref": "#/definitions/language" } },
         { "$ref": "#/definitions/configRefValue" }
       ]
     },
@@ -723,7 +750,7 @@
     },
     "anchor": {
       "type": "object",
-      "anyOf": [{ "required": ["$ref"] }, { "required": ["anchor"] }],
+      "anyOf": [{ "required": ["$ref"] }, { "required": ["anchor", "href"] }],
       "additionalProperties": false,
       "properties": {
         "$ref": { "$ref": "#/definitions/configRef" },
@@ -763,7 +790,10 @@
     },
     "dropdown": {
       "type": "object",
-      "anyOf": [{ "required": ["$ref"] }, { "required": ["dropdown"] }],
+      "allOf": [
+        { "anyOf": [{ "required": ["$ref"] }, { "required": ["dropdown"] }] },
+        { "anyOf": [{ "required": ["$ref"] }, { "required": ["groups"] }, { "required": ["pages"] }] }
+      ],
       "additionalProperties": false,
       "properties": {
         "$ref": { "$ref": "#/definitions/configRef" },
@@ -779,7 +809,10 @@
     },
     "tab": {
       "type": "object",
-      "anyOf": [{ "required": ["$ref"] }, { "required": ["tab"] }],
+      "allOf": [
+        { "anyOf": [{ "required": ["$ref"] }, { "required": ["tab"] }] },
+        { "anyOf": [{ "required": ["$ref"] }, { "required": ["groups"] }, { "required": ["pages"] }, { "required": ["dropdowns"] }] }
+      ],
       "additionalProperties": false,
       "properties": {
         "$ref": { "$ref": "#/definitions/configRef" },
@@ -793,16 +826,28 @@
     },
     "version": {
       "type": "object",
-      "anyOf": [{ "required": ["$ref"] }, { "required": ["version"] }],
+      "allOf": [
+        { "anyOf": [{ "required": ["$ref"] }, { "required": ["version"] }] },
+        { "anyOf": [{ "required": ["$ref"] }, { "required": ["tabs"] }, { "required": ["dropdowns"] }, { "required": ["groups"] }, { "required": ["pages"] }] }
+      ],
+      "not": {
+        "anyOf": [
+          { "required": ["tabs", "dropdowns"] },
+          { "required": ["tabs", "groups"] },
+          { "required": ["tabs", "pages"] },
+          { "required": ["dropdowns", "groups"] },
+          { "required": ["dropdowns", "pages"] }
+        ]
+      },
       "additionalProperties": false,
       "properties": {
         "$ref": { "$ref": "#/definitions/configRef" },
         "version": {
-          "allOf": [{ "$ref": "#/definitions/stringValue" }],
-          "description": "Version label. Only the default (or first) version is rendered."
+          "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
+          "description": "Version label, shown in the version selector. Every version builds; page references determine its URLs."
         },
-        "default": { "allOf": [{ "$ref": "#/definitions/booleanValue" }], "description": "Marks this version as the one to render." },
-        "hidden": { "allOf": [{ "$ref": "#/definitions/booleanValue" }], "description": "Hide this version." },
+        "default": { "allOf": [{ "$ref": "#/definitions/booleanValue" }], "description": "Marks this version as the default. At most one version may be the default; without one, the first visible version is used." },
+        "hidden": { "allOf": [{ "$ref": "#/definitions/booleanValue" }], "description": "Hide this version from the version selector, sitemap, and search. Its pages still build and stay reachable by URL." },
         "tabs": { "$ref": "#/definitions/tabList" },
         "dropdowns": { "$ref": "#/definitions/dropdownList" },
         "groups": { "$ref": "#/definitions/groupList" },
@@ -811,19 +856,35 @@
     },
     "language": {
       "type": "object",
-      "anyOf": [{ "required": ["$ref"] }, { "required": ["language"] }],
+      "allOf": [
+        { "anyOf": [{ "required": ["$ref"] }, { "required": ["language"] }] },
+        { "anyOf": [{ "required": ["$ref"] }, { "required": ["versions"] }, { "required": ["tabs"] }, { "required": ["dropdowns"] }, { "required": ["groups"] }, { "required": ["pages"] }] }
+      ],
+      "not": {
+        "anyOf": [
+          { "required": ["tabs", "dropdowns"] },
+          { "required": ["tabs", "versions"] },
+          { "required": ["tabs", "groups"] },
+          { "required": ["tabs", "pages"] },
+          { "required": ["dropdowns", "versions"] },
+          { "required": ["dropdowns", "groups"] },
+          { "required": ["dropdowns", "pages"] },
+          { "required": ["versions", "groups"] },
+          { "required": ["versions", "pages"] }
+        ]
+      },
       "additionalProperties": false,
       "properties": {
         "$ref": { "$ref": "#/definitions/configRef" },
         "language": {
-          "allOf": [{ "$ref": "#/definitions/stringValue" }],
-          "description": "Language code or label. Only the default (or first) language is rendered."
+          "allOf": [{ "$ref": "#/definitions/nonEmptyStringValue" }],
+          "description": "Language code (e.g. \"es\"), shown in the language selector and used as the page locale when valid. Every language builds; page references determine its URLs."
         },
         "default": {
           "allOf": [{ "$ref": "#/definitions/booleanValue" }],
-          "description": "Marks this language as the one to render."
+          "description": "Marks this language as the default. At most one language may be the default; without one, the first visible language is used."
         },
-        "hidden": { "allOf": [{ "$ref": "#/definitions/booleanValue" }], "description": "Hide this language." },
+        "hidden": { "allOf": [{ "$ref": "#/definitions/booleanValue" }], "description": "Hide this language from the language selector, sitemap, and search. Its pages still build and stay reachable by URL." },
         "versions": { "$ref": "#/definitions/versionList" },
         "tabs": { "$ref": "#/definitions/tabList" },
         "dropdowns": { "$ref": "#/definitions/dropdownList" },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@umami/shiso",
-  "version": "0.61.0",
+  "version": "1.1.0",
   "description": "Open-source documentation framework for Markdown and MDX sites.",
   "type": "module",
   "bin": {
@@ -16,6 +16,7 @@
       "default": "./src/lib/search/provider.ts"
     },
     "./schema": "./docs.schema.json",
+    "./docs.schema.json": "./docs.schema.json",
     "./package.json": "./package.json"
   },
   "files": [
@@ -34,7 +35,7 @@
     "test:package": "node scripts/check-package.mjs"
   },
   "engines": {
-    "node": ">=20"
+    "node": "^20.19.0 || >=22.12.0"
   },
   "repository": {
     "type": "git",

package/scripts/check-package.mjs

@@ -6,6 +6,8 @@ const root = path.resolve(import.meta.dirname, '..');
 for (const relativeFile of [
   'bin/shiso.mjs',
   'docs.schema.json',
+  'scripts/lib/mdast.mjs',
+  'scripts/lib/slug.mjs',
   'src/entry-client.tsx',
   'src/entry-server.tsx',
   'types/client.d.ts',
@@ -15,4 +17,38 @@ for (const relativeFile of [
   await fs.access(path.join(root, relativeFile));
 }
 
+// Every public export subpath must resolve to real files, including its types.
+const metadata = JSON.parse(await fs.readFile(path.join(root, 'package.json'), 'utf8'));
+
+for (const [subpath, target] of Object.entries(metadata.exports)) {
+  const files = typeof target === 'string' ? [target] : Object.values(target);
+
+  for (const file of files) {
+    await fs.access(path.join(root, file)).catch(() => {
+      throw new Error(`Export "${subpath}" points at missing file "${file}".`);
+    });
+  }
+}
+
+// Node scripts must not import raw TypeScript: that would depend on Node's
+// experimental type stripping, which the supported engine range does not have.
+for (const directory of ['bin', 'scripts', 'scripts/lib']) {
+  const entries = await fs.readdir(path.join(root, directory), { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isFile() || !/\.(mjs|js|cjs)$/.test(entry.name)) {
+      continue;
+    }
+
+    const source = await fs.readFile(path.join(root, directory, entry.name), 'utf8');
+    const rawTsImport = source.match(/^import\s[^\n]*from\s+'[^']+\.tsx?';?$/m);
+
+    if (rawTsImport) {
+      throw new Error(
+        `${directory}/${entry.name} imports raw TypeScript: ${rawTsImport[0].trim()}`,
+      );
+    }
+  }
+}
+
 console.log('shiso package contents are ready.');

package/scripts/generate-search-index.mjs

@@ -21,8 +21,8 @@ import remarkGfm from 'remark-gfm';
 import remarkMdx from 'remark-mdx';
 import remarkParse from 'remark-parse';
 import { unified } from 'unified';
-import { headingText } from '../src/lib/mdast.ts';
-import { createSlugger } from '../src/lib/slug.ts';
+import { headingText } from './lib/mdast.mjs';
+import { createSlugger, slugifyId } from './lib/slug.mjs';
 import { loadDocsConfig } from './load-docs-config.mjs';
 
 const DEFAULT_ROOT = process.cwd();
@@ -49,6 +49,53 @@ function normalizePageReference(pageRef) {
   };
 }
 
+/**
+ * One entry per navigation scope, mirroring collectScopeSources in
+ * src/lib/docs-config.ts: ordinary navigation, versions, languages, and
+ * versions nested inside languages. Hidden scopes are excluded from search,
+ * matching how hidden pages are excluded.
+ */
+function collectScopes(navigation) {
+  if (Array.isArray(navigation.versions)) {
+    return navigation.versions
+      .filter(version => !version.hidden)
+      .map(version => ({
+        id: slugifyId(version.version?.trim() || '', 'scope'),
+        version: version.version?.trim(),
+        container: version,
+      }));
+  }
+
+  if (Array.isArray(navigation.languages)) {
+    return navigation.languages
+      .filter(language => !language.hidden)
+      .flatMap(language => {
+        const languageLabel = language.language?.trim();
+
+        if (Array.isArray(language.versions)) {
+          return language.versions
+            .filter(version => !version.hidden)
+            .map(version => ({
+              id: slugifyId(`${languageLabel}-${version.version?.trim()}`, 'scope'),
+              language: languageLabel,
+              version: version.version?.trim(),
+              container: version,
+            }));
+        }
+
+        return [
+          {
+            id: slugifyId(languageLabel || '', 'scope'),
+            language: languageLabel,
+            container: language,
+          },
+        ];
+      });
+  }
+
+  return [{ id: 'default', container: navigation }];
+}
+
 /**
  * Collects `{ fileSlug, slug }` for every non-hidden page in the navigation
  * tree. A simplified mirror of the config walker: search only needs page refs
@@ -62,15 +109,6 @@ function collectVisiblePages(container, pages = [], hidden = false) {
     ...(container.dropdowns || []),
   ];
 
-  // Versions and languages collapse to their default entry, like the app does.
-  for (const key of ['versions', 'languages']) {
-    const entries = container[key];
-
-    if (Array.isArray(entries) && entries.length) {
-      items.push(entries.find(entry => entry.default) || entries[0]);
-    }
-  }
-
   for (const item of items) {
     if (typeof item === 'string') {
       if (!hidden) {
@@ -172,36 +210,44 @@ export async function generateSearchIndex({
   const seen = new Set();
   const records = [];
 
-  for (const { fileSlug, slug } of collectVisiblePages(docsJson.navigation || {})) {
-    if (seen.has(fileSlug)) {
-      continue;
-    }
+  for (const scope of collectScopes(docsJson.navigation || {})) {
+    // Single-scope sites omit scope fields so their index stays unchanged.
+    const scopeFields =
+      scope.id === 'default'
+        ? {}
+        : { scopeId: scope.id, language: scope.language, version: scope.version };
+
+    for (const { fileSlug, slug } of collectVisiblePages(scope.container)) {
+      if (seen.has(fileSlug)) {
+        continue;
+      }
 
-    seen.add(fileSlug);
+      seen.add(fileSlug);
 
-    let source;
-    let filePath;
+      let source;
+      let filePath;
 
-    for (const extension of ['mdx', 'md']) {
-      filePath = path.join(root, contentDir, `${fileSlug}.${extension}`);
-      source = await fs.readFile(filePath, 'utf8').catch(() => undefined);
+      for (const extension of ['mdx', 'md']) {
+        filePath = path.join(root, contentDir, `${fileSlug}.${extension}`);
+        source = await fs.readFile(filePath, 'utf8').catch(() => undefined);
 
-      if (source !== undefined) {
-        break;
+        if (source !== undefined) {
+          break;
+        }
       }
-    }
 
-    if (source === undefined) {
-      // Missing files fail config normalization; search just skips them.
-      continue;
-    }
+      if (source === undefined) {
+        // Missing files fail config normalization; search just skips them.
+        continue;
+      }
 
-    const tree = parser.parse(source);
-    const url = slug === 'index' ? docsPrefix || '/' : `${docsPrefix}/${slug}`;
-    const page = frontmatterTitle(tree) || fileSlug;
+      const tree = parser.parse(source);
+      const url = slug === 'index' ? docsPrefix || '/' : `${docsPrefix}/${slug}`;
+      const page = frontmatterTitle(tree) || fileSlug;
 
-    for (const { heading, id, text } of collectSections(tree)) {
-      records.push({ url, page, heading, id, text });
+      for (const { heading, id, text } of collectSections(tree)) {
+        records.push({ url, page, heading, id, text, ...scopeFields });
+      }
     }
   }
 

package/scripts/lib/mdast.mjs

@@ -0,0 +1,23 @@
+/**
+ * Mirrors the mdast helpers in src/lib/mdast.ts for Node scripts, which must
+ * not import raw TypeScript (that would depend on Node's experimental type
+ * stripping). tests/script-mirrors.test.ts asserts the two stay in sync.
+ */
+
+/** Concatenates the text content of a node, including JSX text children. */
+export function toText(node) {
+  if (!node) {
+    return '';
+  }
+
+  if (typeof node.value === 'string') {
+    return node.value;
+  }
+
+  return (node.children || []).map(toText).join('');
+}
+
+/** Text of a heading node, trimmed. */
+export function headingText(node) {
+  return toText(node).trim();
+}

package/scripts/lib/slug.mjs

@@ -0,0 +1,21 @@
+/**
+ * Mirrors src/lib/slug.ts for Node scripts, which must not import raw
+ * TypeScript (that would depend on Node's experimental type stripping).
+ * tests/script-mirrors.test.ts asserts the two stay in sync.
+ */
+import GithubSlugger, { slug as slugifyOnce } from 'github-slugger';
+
+/** Stateful slugger matching rehype-slug: repeated headings get -1, -2, ... */
+export function createSlugger() {
+  return new GithubSlugger();
+}
+
+/** Stateless slugify for one-off ids that do not need de-duplication. */
+export function slugify(value) {
+  return slugifyOnce(value.trim());
+}
+
+/** Slugifies a label into a config-level identifier, with a fallback. */
+export function slugifyId(value, fallback) {
+  return slugify(value) || fallback;
+}

package/scripts/prerender.mjs

@@ -16,7 +16,6 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import process from 'node:process';
 import { pathToFileURL } from 'node:url';
-import { loadDocsConfig } from './load-docs-config.mjs';
 
 const DEFAULT_HEAD_OPEN = '<!--shiso-default-head-->';
 const DEFAULT_HEAD_CLOSE = '<!--/shiso-default-head-->';
@@ -32,12 +31,8 @@ if (!template.includes('<!--app-html-->')) {
   );
 }
 
-const { config: docsJson } = await loadDocsConfig({ root });
-const docsPrefix = (docsJson.$shiso?.docsPrefix ?? '/docs').replace(/\/+$/, '');
-
-const { render, getRoutes, getRedirects, getSitemapEntries, getMarkdownPages } = await import(
-  pathToFileURL(path.join(root, 'dist', 'server', 'entry-server.js')).href
-);
+const { render, getRoutes, getRedirects, getSitemapEntries, getMarkdownPages, docsHomeUrl } =
+  await import(pathToFileURL(path.join(root, 'dist', 'server', 'entry-server.js')).href);
 
 /** Vite's `base`, normalized to "" or "/prefix". */
 function readBase() {
@@ -52,12 +47,21 @@ function withBase(routePath) {
   return `${base}${routePath}`.replace(/\/{2,}/g, '/') || '/';
 }
 
-function fillTemplate(head, html) {
+function fillTemplate(head, html, htmlAttrs) {
   // Per-page head tags supersede the site-level defaults injected at build time.
-  const output = head
+  let output = head
     ? template.replace(new RegExp(`${DEFAULT_HEAD_OPEN}[\\s\\S]*?${DEFAULT_HEAD_CLOSE}`), '')
     : template;
 
+  // Per-page document language and direction, replacing the template's own.
+  if (htmlAttrs) {
+    output = output.replace(/<html([^>]*)>/, (_match, attrs) => {
+      const kept = attrs.replace(/\s+lang="[^"]*"/, '').replace(/\s+dir="[^"]*"/, '');
+      const dir = htmlAttrs.dir === 'rtl' ? ' dir="rtl"' : '';
+      return `<html${kept} lang="${htmlAttrs.lang}"${dir}>`;
+    });
+  }
+
   return output.replace('<!--app-head-->', head).replace('<!--app-html-->', html);
 }
 
@@ -75,15 +79,15 @@ function outputPathFor(routePath) {
 const routes = getRoutes();
 
 for (const route of routes) {
-  const { html, head } = render(route);
-  await writePage(outputPathFor(route), fillTemplate(head, html));
+  const { html, head, htmlAttrs } = render(route);
+  await writePage(outputPathFor(route), fillTemplate(head, html, htmlAttrs));
 }
 
-// Root entry. When docs live at a prefix the root is a redirect; a meta refresh
-// alone is slow and SEO-hostile, so pair it with a canonical link and an
-// immediate history-replacing navigation.
-if (docsPrefix) {
-  const target = withBase(`${docsPrefix}/`);
+// Root entry. When the default scope's landing page is not the root itself the
+// root is a redirect; a meta refresh alone is slow and SEO-hostile, so pair it
+// with a canonical link and an immediate history-replacing navigation.
+if (docsHomeUrl && docsHomeUrl !== '/') {
+  const target = withBase(`${docsHomeUrl}/`);
 
   await writePage(
     path.join(clientDir, 'index.html'),
@@ -166,7 +170,10 @@ if (sitemapEntries.length) {
 // 404 fallback renders the app shell so client routing can take over
 // on hosts that serve 404.html for unknown paths (e.g. GitHub Pages).
 const notFound = render('/404');
-await writePage(path.join(clientDir, '404.html'), fillTemplate(notFound.head, notFound.html));
+await writePage(
+  path.join(clientDir, '404.html'),
+  fillTemplate(notFound.head, notFound.html, notFound.htmlAttrs),
+);
 
 // Guard against a base/route mismatch silently producing unreachable files.
 const stray = routes.filter(route => !withBase(route).startsWith(base || '/'));

package/src/App.tsx

@@ -11,8 +11,7 @@ import { CodeBlock } from '@/components/CodeBlock';
 import * as docsComponents from '@/components/docs/index';
 import { Layout } from '@/components/Layout';
 import { TooltipProvider } from '@/components/ui/tooltip';
-import { DOCS_PREFIX } from '@/lib/paths';
-import { siteModel } from '@/lib/site-config';
+import { docsHomeUrl, siteModel } from '@/lib/site-config';
 import { DocPage } from '@/pages/DocPage';
 
 const mdxComponents = {
@@ -26,9 +25,9 @@ export function App() {
       <MDXProvider components={mdxComponents}>
         <Layout site={siteModel}>
           <Routes>
-            {/* When docs are mounted at the site root there is nothing to redirect. */}
-            {DOCS_PREFIX ? (
-              <Route path="/" element={<Navigate to={DOCS_PREFIX} replace />} />
+            {/* When the default scope's landing page is the root there is nothing to redirect. */}
+            {docsHomeUrl !== '/' ? (
+              <Route path="/" element={<Navigate to={docsHomeUrl} replace />} />
             ) : null}
             <Route path="*" element={<DocPage site={siteModel} />} />
           </Routes>

package/src/components/DocContent.tsx

@@ -2,6 +2,9 @@ import { Link } from 'react-router';
 import { ContextualMenu } from '@/components/ContextualMenu';
 import { ChevronRight } from '@/components/icons';
 import { getLastModified } from '@/lib/content';
+import { getScopeForPage } from '@/lib/docs-config';
+import { resolveLocale } from '@/lib/locale';
+import { docsSite } from '@/lib/site-config';
 import { resolveContextualOptions } from '@/lib/site-model';
 import type { DocModule, NormalizedDocsPage, SiteModel } from '@/lib/types';
 
@@ -12,7 +15,8 @@ export interface DocContentProps {
 }
 
 export function DocContent({ page, doc, site }: DocContentProps) {
-  const pagerPages = site.docs.pages.filter(item => !item.hidden);
+  // Prev/next paging never crosses a version or language boundary.
+  const pagerPages = getScopeForPage(docsSite, page).docs.pages.filter(item => !item.hidden);
   const pageIndex = pagerPages.findIndex(item => item.slug === page.slug);
   const prev = pageIndex > 0 ? pagerPages[pageIndex - 1] : undefined;
   const next = pageIndex >= 0 ? pagerPages[pageIndex + 1] : undefined;
@@ -30,7 +34,8 @@ export function DocContent({ page, doc, site }: DocContentProps) {
       ? [...new Set([page.tabLabel, page.section])].filter(Boolean).join(' / ')
       : page.section;
   const contextualOptions = resolveContextualOptions(site.contextualOptions, page, site.labels);
-  const dateFormat = new Intl.DateTimeFormat(site.locale, {
+  // Dates follow the page's language when it is a valid locale code.
+  const dateFormat = new Intl.DateTimeFormat(resolveLocale(page.language, site.locale), {
     dateStyle: 'medium',
     timeZone: 'UTC',
   });