@waveso/docs 0.4.0 → 0.6.0

package/dist/link-suggestion.js

@@ -0,0 +1,94 @@
+//#region src/link-suggestion.ts
+/**
+* "Did you mean …?" for a link that matched no page.
+*
+* Private — deliberately not an entry point.
+*
+* A broken link is almost always a typo, and a typo is a near-miss by
+* construction: `/instalation` is one edit from `/installation`, while `/login`
+* is six from anything in a docs tree. That gap is what makes a suggestion
+* safe to offer and safe to withhold — the same reason `git`, `tsc`, `cargo`
+* and Python 3.12 all do it, and the reason none of them offers one for a word
+* that is nowhere near a real name.
+*
+* ⚠️ A SUGGESTION ONLY, NEVER A DECISION. Nothing here decides whether a link
+* is an error; `render.ts` has already decided that by the time it asks. Using
+* an edit distance to pick between failing and staying silent would be a
+* heuristic holding a build hostage, which is not a thing to do to somebody
+* whose page happens to be called `/setting`.
+*/
+/**
+* The ceiling on how far apart two routes may be and still be called a typo.
+*
+* Three is roughly one slip per word in a two-word slug — `instalation`,
+* `gettting-started`, `plugns`. It is a *ceiling*, not the whole rule: the
+* budget is also scaled by the length of what was written, so short routes are
+* held tighter and `/api` is not offered as a fix for `/ui`.
+*
+* Between them, `/docs/instructions` gets no suggestion for
+* `/docs/installation` — five edits apart, similar enough to tempt a generous
+* threshold, and a different word. `render.test.ts` pins that case, because
+* without it this constant could be any number at all.
+*/
+const MAX_DISTANCE = 3;
+/**
+* Levenshtein distance, bounded.
+*
+* Two rows rather than a full matrix: the corpus is every route on the site and
+* this runs per broken link, so the allocation is the only part worth caring
+* about. Returns early once every cell in a row exceeds `limit`, which is the
+* common case — most candidates are nowhere near.
+*/
+function distance(a, b, limit) {
+	if (a === b) return 0;
+	if (Math.abs(a.length - b.length) > limit) return limit + 1;
+	let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+	let current = new Array(b.length + 1);
+	for (let i = 1; i <= a.length; i += 1) {
+		current[0] = i;
+		let best = i;
+		for (let j = 1; j <= b.length; j += 1) {
+			const substitution = previous[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1);
+			const deletion = previous[j] + 1;
+			const insertion = current[j - 1] + 1;
+			const cell = Math.min(substitution, deletion, insertion);
+			current[j] = cell;
+			if (cell < best) best = cell;
+		}
+		if (best > limit) return limit + 1;
+		const swap = previous;
+		previous = current;
+		current = swap;
+	}
+	return previous[b.length];
+}
+/**
+* The closest route to `target`, or `undefined` if nothing is close enough.
+*
+* Ties break on the shortest candidate and then alphabetically, so the message
+* is the same on every machine — a suggestion that changes between runs reads
+* as a flaky build.
+*/
+function suggestRoute(target, routes) {
+	const limit = Math.min(MAX_DISTANCE, Math.max(1, Math.floor(target.length / 3)));
+	let best;
+	let bestDistance = limit + 1;
+	for (const route of routes) {
+		if (route === target) continue;
+		const measured = distance(target, route, limit);
+		if (measured > limit) continue;
+		if (measured < bestDistance || measured === bestDistance && best !== void 0 && (route.length < best.length || route.length === best.length && route < best)) {
+			best = route;
+			bestDistance = measured;
+		}
+	}
+	return best;
+}
+/** ` Did you mean '/installation'?`, or `''` when nothing is close. */
+function describeSuggestion(target, routes) {
+	if (routes === void 0) return "";
+	const suggestion = suggestRoute(target, routes);
+	return suggestion === void 0 ? "" : ` Did you mean '${suggestion}'?`;
+}
+//#endregion
+export { describeSuggestion, suggestRoute };

package/dist/meta.js

@@ -1,4 +1,5 @@
 import { docsError } from "./docs-error.js";
+import { isSafeHref, opensInNewTab } from "./safe-href.js";
 import { z } from "zod";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
@@ -16,11 +17,6 @@ const SEPARATOR_PATTERN = /^---(.+)---$/;
 /** The rest wildcard: everything not named explicitly, in place. */
 const REST = "...";
 /**
-* `<scheme>:` or protocol-relative `//host` — i.e. a URL that leaves the site.
-* Anything else (`/changelog`, `../pricing`) is internal.
-*/
-const ABSOLUTE_HREF_PATTERN = /^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/\/)/;
-/**
 * Zod mirror of {@link DocsMeta}.
 *
 * Strict on purpose: `meta.json` is hand-written and unvalidated keys are
@@ -31,7 +27,7 @@ const docsMetaSchema = z.strictObject({
 	title: z.string().exactOptional(),
 	pages: z.array(z.union([z.string(), z.strictObject({
 		title: z.string(),
-		href: z.string()
+		href: z.string().refine(isSafeHref, { message: "that is not a scheme this package will put in a link. Use http(s), mailto, tel, sms, ftp, irc, xmpp, news, feed, git or matrix — or a path, which needs no scheme at all." })
 	})])).exactOptional()
 });
 /**
@@ -58,7 +54,7 @@ async function readDocsMeta(dirPath) {
 	}
 	let parsed;
 	try {
-		parsed = JSON.parse(raw);
+		parsed = JSON.parse(raw.charCodeAt(0) === 65279 ? raw.slice(1) : raw);
 	} catch (err) {
 		const reason = err instanceof Error ? err.message : String(err);
 		throw docsError("invalid-meta", `Could not parse ${filePath} as JSON: ${reason}`, { cause: err });
@@ -90,13 +86,14 @@ function orderNavEntries(entries, meta, metaPath, depth) {
 	const used = /* @__PURE__ */ new Set();
 	const nodes = [];
 	let restAt = -1;
-	for (const page of pages) {
+	for (const raw of pages) {
+		const page = typeof raw === "string" ? raw.normalize("NFC") : raw;
 		if (typeof page !== "string") {
 			nodes.push({
 				type: "link",
 				title: page.title,
 				href: page.href,
-				external: ABSOLUTE_HREF_PATTERN.test(page.href)
+				external: opensInNewTab(page.href)
 			});
 			continue;
 		}

package/dist/next.d.ts

@@ -1,7 +1,8 @@
 import { DocFile, DocFrontmatter, DocsConfig, ImageResolver, LinkResolver, RenderedDoc, SearchRecord } from "./types.js";
 import { DocsHighlighter, DocsLang, DocsTheme, DocsThemes } from "./highlighter.js";
-import { MarkdownComponents } from "./react/markdown-components.js";
+import { SerializableSearchOptions } from "./search-options.js";
 import { DocsLabels } from "./react/shell-labels.js";
+import { MarkdownComponents } from "./react/markdown-components.js";
 import { DocsLayoutSearchProps } from "./react/layout.js";
 import { DocsSource } from "./source.js";
 import { ReactNode } from "react";
@@ -61,13 +62,36 @@ interface DocsRouteOptions<TFrontmatter extends DocFrontmatter = DocFrontmatter>
   /**
    * MiniSearch overrides for the index {@link DocsRoute.searchIndex} builds.
    *
-   * ⚠️ THE IDENTICAL OBJECT MUST REACH THE DIALOG — pass it to `DocsSearch`'s
-   * (or `SearchDialog`'s) `miniSearchOptions`. MiniSearch reads `tokenize` and
-   * `processTerm` both when indexing and when querying, so applying one here
-   * and not there produces an index whose terms no query can spell: zero
+   * ⚠️ THE IDENTICAL OBJECT MUST REACH THE DIALOG. MiniSearch reads `tokenize`
+   * and `processTerm` both when indexing and when querying, so applying one
+   * here and not there produces an index whose terms no query can spell: zero
    * results, no error, nothing in the console.
+   *
+   * {@link DocsRoute.Layout} forwards this for you, which covers every
+   * serialisable override — `storeFields`, `boost`, `searchOptions.fuzzy`. It
+   * cannot forward a **function**: the dialog is a Client Component and props
+   * crossing that boundary are serialised, so `tokenize`, `processTerm` and
+   * their kind make `next build` fail. Rather than drop them silently — which
+   * is the zero-results failure above, with the warning turned off — `Layout`
+   * throws `invalid-config` and names the remedy: pass `search={false}`, render
+   * `DocsSearch` from a `'use client'` module of your own, and import the same
+   * function there. See {@link SerializableSearchOptions}.
    */
   miniSearchOptions?: Partial<Options<SearchRecord>> | undefined;
+  /**
+   * Every string this package renders that is not your content.
+   *
+   * ⚠️ THE ROUTE IS WHERE THEY BELONG, BECAUSE THEY DO NOT ALL LIVE IN ONE
+   * RUNTIME. Four are rendered by the shell, two by the table of contents, nine
+   * by the markdown component map, two by a client-side copy runtime — and two
+   * are baked into the HTML by a rehype plugin at build time. `docs.Layout` can
+   * reach the first four and no more, which is exactly why its own `labels` prop
+   * documented itself as the whole set and covered less than a fifth of it.
+   *
+   * `docs.Layout` forwards these for you, and its `labels` prop still overrides
+   * them per-layout. Set them once here.
+   */
+  labels?: DocsLabels | undefined;
 }
 /**
  * Props for {@link DocsRoute.Layout}.
@@ -97,23 +121,39 @@ interface DocsLayoutProps {
    * The search trigger. Defaults to on, and the URL is always derived.
    *
    * `false` omits it. An object configures the dialog — `placeholder`,
-   * `hotkey`, `miniSearchOptions` and the rest of `DocsSearch`'s surface,
-   * minus `indexUrl`.
+   * `pageSize`, `minQueryLength`, the state messages and the rest of
+   * `DocsSearch`'s surface, minus `indexUrl`.
+   *
+   * (It used to say `hotkey`. There is no such prop and there never was: the
+   * shortcut is ⌘K / Ctrl-K and is not configurable. A docstring naming an
+   * option that does not exist is worse than one naming none.)
    *
    * You do not need to pass `miniSearchOptions` here to match what
    * `createDocsRoute` was given: the route's own value is forwarded, so the
    * object that built the index is the object that queries it. Pass one only
    * to override that.
+   *
+   * Serialisable overrides only, in both directions. This is a Server
+   * Component handing props to a Client one, so a `tokenize` or a
+   * `processTerm` here does not compile and one on the route throws rather
+   * than being quietly dropped — {@link SerializableSearchOptions} has the
+   * `'use client'` recipe for those.
    */
   search?: boolean | DocsLayoutSearchProps | undefined;
   /**
-   * The four strings the shell renders itself: the navigation landmark's name,
-   * the drawer's open and close buttons, and the skip link.
+   * Overrides for the strings the shell renders, over the route's.
+   *
+   * ⚠️ THIS DOCSTRING USED TO CLAIM TO BE "THE WHOLE OF WHAT A NON-ENGLISH SITE
+   * HAS TO SAY" AND REACHED FOUR STRINGS OF TWENTY-TWO. It could not have
+   * reached the rest: the table of contents is rendered by `docs.Page`, the
+   * callout headings by a component map built when the route is created, and the
+   * copy button is baked into the HTML by a rehype plugin at build time. None of
+   * those is downstream of a layout prop.
    *
-   * Everything else a reader sees is your markdown or your `title`. This is the
-   * whole of what a non-English site has to say — and it is the fifth prop,
-   * added deliberately: a documentation shell nobody can translate is not a
-   * shell for the whole ecosystem.
+   * So the set lives on {@link DocsRouteOptions.labels}, which is upstream of
+   * all four runtimes, and this overrides it key by key — for a site with two
+   * shells, or a section in another language. Whole-object replacement would
+   * mean naming one string cost you the other twenty-one.
    */
   labels?: DocsLabels | undefined;
 }
@@ -400,4 +440,4 @@ interface DocsRedirect {
  */
 declare function createDocsRedirects(config: DocsConfig): Promise<DocsRedirect[]>;
 //#endregion
-export { type DocsLang, DocsLayoutProps, DocsPageMetadata, DocsPageProps, DocsRedirect, DocsRoute, DocsRouteOptions, DocsSitemapEntry, DocsSitemapOptions, type DocsTheme, type DocsThemes, createDocsRedirects, createDocsRoute, createDocsSitemap };
+export { type DocsLang, DocsLayoutProps, type DocsLayoutSearchProps, DocsPageMetadata, DocsPageProps, DocsRedirect, DocsRoute, DocsRouteOptions, DocsSitemapEntry, DocsSitemapOptions, type DocsTheme, type DocsThemes, type SerializableSearchOptions, createDocsRedirects, createDocsRoute, createDocsSitemap };

package/dist/next.js

@@ -1,10 +1,13 @@
+import { assertAnchors } from "./anchors.js";
 import { docsError } from "./docs-error.js";
 import { DOCS_CONTENT_ID } from "./docs-content-id.js";
+import { describeSuggestion } from "./link-suggestion.js";
 import { mapPooled } from "./map-pooled.js";
+import { findFunctionValuedOptions } from "./search-options.js";
 import { createMarkdownComponents } from "./react/markdown-components.js";
 import { DocContent } from "./react/doc-content.js";
 import { DocsToc } from "./react/toc.js";
-import { wrapNextLink } from "./react/next-link.js";
+import { wrapNextLink } from "./react/link-adapter.js";
 import { createDocsRenderer } from "./render.js";
 import { toAliasRoute } from "./route-path.js";
 import { createDocsSource, resolveDocsConfig } from "./source.js";
@@ -119,9 +122,14 @@ async function loadNotFound() {
 * as `number | \`${number}\``, and spreading a `ComponentProps<'img'>`-shaped
 * object into it fails with TS2322 because the DOM types allow a bare `string`.
 * The build-time {@link ImageResolver} has already produced real numbers here.
+*
+* ⚠️ SO THE LIST IS THE CONTRACT, AND IT HAS TO MATCH `DocsImageProps`. A prop
+* added there and forgotten here is dropped silently — which is what happened to
+* `decoding` and `fetchPriority`, under a comment in `createImage` promising
+* they survived.
 */
 function wrapNextImage(NextImage) {
-	return function DocsNextImage({ src, alt, width, height, title, className, sizes, loading }) {
+	return function DocsNextImage({ src, alt, width, height, title, className, sizes, loading, decoding, fetchPriority }) {
 		return createElement(NextImage, {
 			src,
 			alt,
@@ -130,35 +138,92 @@ function wrapNextImage(NextImage) {
 			...title === void 0 ? {} : { title },
 			...className === void 0 ? {} : { className },
 			...sizes === void 0 ? {} : { sizes },
-			...loading === void 0 ? {} : { loading }
+			...loading === void 0 ? {} : { loading },
+			...decoding === void 0 ? {} : { decoding },
+			...fetchPriority === void 0 ? {} : { fetchPriority }
 		});
 	};
 }
 /**
-* The component map is built once per process.
+* A memo for the component map, one per route.
 *
 * `createMarkdownComponents` returns fresh component identities on every call,
 * and a new identity for `a` remounts every link in the document on every
 * render — so this memo is correctness, not micro-optimisation.
+*
+* ⚠️ PER ROUTE, NOT PER PROCESS, SINCE THE MAP CLOSES OVER THE ROUTE'S LABELS.
+* A single process-wide memo would hand the second route the first route's
+* language. Nothing is lost: `import()` caches the `next/link` and `next/image`
+* modules itself, so all a second route pays for is two wrapper identities —
+* and a route's identities only ever have to be stable against themselves,
+* because the pages that use them come from that same route.
 */
-let nextComponents = null;
-function loadNextComponents() {
-	if (nextComponents === null) nextComponents = buildNextComponents().catch((error) => {
-		nextComponents = null;
-		throw error;
-	});
-	return nextComponents;
+function createComponentsMemo(labels) {
+	let memo = null;
+	return () => {
+		if (memo === null) memo = buildNextComponents(labels).catch((error) => {
+			memo = null;
+			throw error;
+		});
+		return memo;
+	};
 }
-async function buildNextComponents() {
+async function buildNextComponents(labels) {
 	const [linkMod, imageMod] = await Promise.all([importNext(() => import("next/link"), "next/link"), importNext(() => import("next/image"), "next/image")]);
 	const NextLink = readDefaultExport(linkMod, "next/link");
 	const NextImage = readDefaultExport(imageMod, "next/image");
 	return createMarkdownComponents({
 		Link: wrapNextLink(NextLink),
-		Image: wrapNextImage(NextImage)
+		Image: wrapNextImage(NextImage),
+		...labels === void 0 ? {} : { labels }
 	});
 }
 /**
+* The named subset of `labels`, or `undefined` when none of it is set.
+*
+* `undefined` rather than `{}` is the point: every forwarding site here spreads
+* with `...(x === undefined ? {} : { x })`, so an empty object would still add a
+* prop — and for the two groups that cross a client boundary that is a prop in
+* every page's payload, forever, saying nothing.
+*
+* `map` goes target-key → `DocsLabels` key, so the rename is visible at the call
+* site rather than hidden in a component.
+*/
+function pickLabels(labels, map) {
+	if (labels === void 0) return void 0;
+	const picked = {};
+	let found = false;
+	for (const [target, source] of Object.entries(map)) {
+		const value = labels[source];
+		if (value !== void 0) {
+			picked[target] = value;
+			found = true;
+		}
+	}
+	return found ? picked : void 0;
+}
+/**
+* `candidate`, once it is known to hold no functions.
+*
+* The cast at the end is the whole point of the function, and
+* {@link findFunctionValuedOptions} is what earns it: a structural walk over
+* the values, so it answers for options MiniSearch has not shipped yet as well
+* as the five it has. `SerializableSearchOptions` narrows the same thing at
+* compile time, which is friendlier and strictly weaker — a JavaScript caller
+* has no types at all, and an `Omit` list goes stale the minor MiniSearch adds
+* a callback.
+*
+* Throwing beats dropping. Silently forwarding the serialisable half would
+* rebuild the original defect this channel exists to close — an index built
+* with a `processTerm` the query does not share returns nothing, reports
+* nothing, and looks like an empty corpus.
+*/
+function serializableSearchOptions(candidate) {
+	const functions = findFunctionValuedOptions(candidate);
+	if (functions.length > 0) throw docsError("invalid-config", `the search dialog cannot be given MiniSearch functions from a server component: ${functions.map((name) => `\`miniSearchOptions.${name}\``).join(", ")}. \`docs.Layout\` renders the dialog as a client component, so its props are serialised on the way across and React rejects a function with "Functions cannot be passed directly to Client Components" while prerendering. Keep the function on \`createDocsRoute\` so the index is still built with it, pass \`search={false}\` to \`docs.Layout\`, and render the dialog yourself from a \`'use client'\` module that imports the same function — \`<DocsSearch indexUrl={docs.searchIndexUrl} miniSearchOptions={{ processTerm }} />\` — putting that component in \`actions\`. Serialisable overrides (\`storeFields\`, \`boost\`, \`searchOptions.fuzzy\`) need none of this and are forwarded as before.`);
+	return candidate;
+}
+/**
 * Create the route handlers for a documentation tree.
 *
 * Call it once at module scope in each of the two route files. The filesystem
@@ -170,6 +235,28 @@ function createDocsRoute(options) {
 	const source = createDocsSource(options);
 	const siteUrl = normalizeSiteUrl(options.siteUrl);
 	const rescanPerRequest = process.env.NODE_ENV !== "production";
+	const routeLabels = options.labels;
+	const codeLabels = pickLabels(routeLabels, {
+		copyLabel: "copyCode",
+		copyFromLabel: "copyCodeFrom"
+	});
+	const contentLabels = pickLabels(routeLabels, {
+		externalLink: "externalLink",
+		table: "table",
+		calloutNote: "calloutNote",
+		calloutTip: "calloutTip",
+		calloutImportant: "calloutImportant",
+		calloutWarning: "calloutWarning",
+		calloutCaution: "calloutCaution",
+		youtubeTitle: "youtubeTitle",
+		youtubePlay: "youtubePlay",
+		youtubeHide: "youtubeHide"
+	});
+	const copyLabels = pickLabels(routeLabels, {
+		copied: "copied",
+		copyFailed: "copyFailed"
+	});
+	const loadComponents = createComponentsMemo(contentLabels);
 	let renderer = null;
 	const knownRoutes = /* @__PURE__ */ new Set();
 	const draftRoutes = /* @__PURE__ */ new Set();
@@ -232,6 +319,7 @@ function createDocsRoute(options) {
 		...options.langs === void 0 ? {} : { langs: options.langs },
 		...options.themes === void 0 ? {} : { themes: options.themes },
 		...options.excludeLangs === void 0 ? {} : { excludeLangs: options.excludeLangs },
+		...codeLabels === void 0 ? {} : { codeLabels },
 		...options.titleHeading === void 0 ? {} : { titleHeading: options.titleHeading },
 		...options.remarkPlugins === void 0 ? {} : { remarkPlugins: options.remarkPlugins },
 		...options.rehypePlugins === void 0 ? {} : { rehypePlugins: options.rehypePlugins },
@@ -288,7 +376,23 @@ function createDocsRoute(options) {
 		const files = await source.all();
 		await loadRoutes();
 		const renderer = loadRenderer();
-		return mapPooled(files, RENDER_CONCURRENCY, (file) => renderer.render(file));
+		const rendered = await mapPooled(files, RENDER_CONCURRENCY, (file) => renderer.render(file));
+		assertAnchors(rendered, (from, link, known) => {
+			reportAnchor(`@waveso/docs: ${from} links to '${link.href}', and '${link.route}' has no '#${link.fragment}'.${describeSuggestion(link.fragment, known)} Heading ids come from the heading text, so renaming a heading renames its anchor.`);
+		});
+		return rendered;
+	};
+	/**
+	* A cross-page anchor failure, at the configured severity.
+	*
+	* No line number, unlike the same-page check: positions are stripped from a
+	* returned tree, so the page and the link are what there is to name. Both
+	* halves share `onBrokenAnchors`, because to an author they are one mistake.
+	*/
+	const reportAnchor = (message) => {
+		if (config.onBrokenAnchors === "ignore") return;
+		if (config.onBrokenAnchors === "throw") throw docsError("broken-anchor", message);
+		console.warn(message);
 	};
 	const searchIndexUrl = `${config.basePath}/search-index.json`;
 	/**
@@ -321,7 +425,7 @@ function createDocsRoute(options) {
 	async function renderRoute(segments) {
 		const doc = await getPage(segments);
 		if (doc === void 0) return (await loadNotFound())();
-		const components = await loadNextComponents();
+		const components = await loadComponents();
 		return createElement(Fragment, null, createElement("main", {
 			className: "wave-docs-layout__main",
 			id: DOCS_CONTENT_ID,
@@ -331,8 +435,13 @@ function createDocsRoute(options) {
 			components: {
 				...components,
 				...options.components
-			}
-		})), doc.toc.length === 0 ? null : createElement("aside", { className: "wave-docs-layout__toc" }, createElement(DocsToc, { entries: doc.toc })));
+			},
+			...copyLabels === void 0 ? {} : { labels: copyLabels }
+		})), doc.toc.length === 0 ? null : createElement("aside", { className: "wave-docs-layout__toc" }, createElement(DocsToc, {
+			entries: doc.toc,
+			...routeLabels?.toc === void 0 ? {} : { label: routeLabels.toc },
+			...routeLabels?.backToTop === void 0 ? {} : { topLabel: routeLabels.backToTop }
+		})));
 	}
 	return {
 		source: requestScopedSource,
@@ -350,9 +459,15 @@ function createDocsRoute(options) {
 		},
 		async Layout({ children, title, actions, search, labels }) {
 			const { DocsLayoutShell } = await import("./react/layout.js");
+			const host = search === true || search === void 0 || search === false ? void 0 : search;
+			const requestedOptions = host?.miniSearchOptions ?? options.miniSearchOptions;
 			const searchProps = search === false ? false : {
-				...options.miniSearchOptions === void 0 ? {} : { miniSearchOptions: options.miniSearchOptions },
-				...search === true || search === void 0 ? {} : search
+				...host,
+				...requestedOptions === void 0 ? {} : { miniSearchOptions: serializableSearchOptions(requestedOptions) }
+			};
+			const shellLabels = options.labels === void 0 && labels === void 0 ? void 0 : {
+				...options.labels,
+				...labels
 			};
 			return createElement(DocsLayoutShell, {
 				children,
@@ -361,7 +476,7 @@ function createDocsRoute(options) {
 				search: searchProps,
 				...title === void 0 ? {} : { title },
 				...actions === void 0 ? {} : { actions },
-				...labels === void 0 ? {} : { labels }
+				...shellLabels === void 0 ? {} : { labels: shellLabels }
 			});
 		},
 		async generateStaticParams() {

package/dist/plugins/rehype-code-frame.d.ts

@@ -2,8 +2,20 @@ import { Plugin } from "unified";
 import { Root } from "hast";
 //#region src/plugins/rehype-code-frame.d.ts
 interface RehypeCodeFrameOptions {
-  /** Accessible name when a fence has no title. */
+  /**
+   * Accessible name of the copy button on a fence with no title.
+   * Default `'Copy code'`.
+   */
   copyLabel?: string | undefined;
+  /**
+   * The same button on a titled fence. Default `'Copy code from {title}'`.
+   *
+   * `{title}` is replaced with the fence's own `title="…"`. Two controls both
+   * called "Copy code" are indistinguishable in a screen reader's element list,
+   * which is why the titled form exists at all — and a translator needs to be
+   * able to move the title within the sentence, which concatenation forbade.
+   */
+  copyFromLabel?: string | undefined;
 }
 declare const rehypeCodeFrame: Plugin<[RehypeCodeFrameOptions?], Root>;
 //#endregion

package/dist/plugins/rehype-code-frame.js

@@ -6,6 +6,7 @@ import { CONTINUE, SKIP, visit } from "unist-util-visit";
 const LANGUAGE_CLASS = /^language-(.+)$/;
 const rehypeCodeFrame = (options = {}) => {
 	const copyLabel = options.copyLabel ?? "Copy code";
+	const copyFromLabel = options.copyFromLabel ?? "Copy code from {title}";
 	return (tree, file) => {
 		const path = file.data.docLinkContext?.relativePath ?? file.path ?? "a document";
 		visit(tree, "element", (node, index, parent) => {
@@ -27,7 +28,7 @@ const rehypeCodeFrame = (options = {}) => {
 					value: title
 				}]
 			});
-			children.push(copyButton(title === void 0 ? copyLabel : `${copyLabel} from ${title}`), node);
+			children.push(copyButton(title === void 0 ? copyLabel : copyFromLabel.replace("{title}", title)), node);
 			parent.children[index] = {
 				type: "element",
 				tagName: "figure",

package/dist/plugins/rehype-fallback-heading-ids.js

@@ -1,6 +1,6 @@
+import { visit } from "unist-util-visit";
 import rehypeSlug from "rehype-slug";
 import { unified } from "unified";
-import { visit } from "unist-util-visit";
 //#region src/plugins/rehype-fallback-heading-ids.ts
 const HEADING = /^h[1-6]$/;
 /** `-1`, `-2` … — what `github-slugger` returns for a repeated empty slug. */

package/dist/plugins/remark-doc-links.d.ts

@@ -26,6 +26,36 @@ interface DocLinkRef {
    * never be a member of.
    */
   asset?: true;
+  /**
+   * An absolute link at a root mount, which cannot be proved to be ours.
+   *
+   * ⚠️ RECORDED RATHER THAN SKIPPED, WHICH IS THE CHANGE. Under
+   * `basePath: '/docs'` an absolute link either starts with `/docs` — so it is
+   * a documentation route and is checked — or it does not, and belongs to the
+   * host's application. Under `basePath: '/'` that test cannot be made:
+   * `/setup` may be a page here and `/login` almost certainly is not, and
+   * nothing in the markdown says which.
+   *
+   * So it is collected and marked, and checked like any other link — because a
+   * root mount is what you choose when the origin serves documentation and
+   * nothing else, which makes an unknown absolute link a typo. An origin that
+   * serves something else names what is its own through
+   * `DocsConfig.externalRoutes`.
+   */
+  unverifiable?: true;
+  /**
+   * A bare `#fragment` — a link into the page it is written on.
+   *
+   * ⚠️ RECORDED SO THE ANCHOR CAN BE CHECKED, AND FLAGGED SO THE ROUTE IS NOT.
+   * `isRelativeLink` excludes these and always did, correctly: there is no
+   * route to resolve. But that also meant they were never collected, so nothing
+   * downstream could see `#missing` at all — and a same-page anchor is the one
+   * a writer produces most, every "see below".
+   *
+   * `assertLinks` skips these; `assertOwnAnchors` is what reads them, and the
+   * recorded line is why the message can name one.
+   */
+  anchorOnly?: true;
 }
 declare module 'vfile' {
   interface DataMap {
@@ -41,6 +71,8 @@ interface RemarkDocLinksOptions {
   /** Overrides the built-in resolution entirely, for every relative link. */
   resolve?: LinkResolver;
 }
+/** No prefix at all — the docs own the whole origin. */
+declare function isRootMount(basePath: string): boolean;
 /**
  * Fold `.` and `..` against a starting directory.
  *
@@ -56,6 +88,56 @@ interface RemarkDocLinksOptions {
  * are contained by one implementation rather than two.
  */
 declare function foldSegments(from: readonly string[], path: string): string[] | undefined;
+/**
+ * Decode BEFORE folding, never after: `%2E%2E%2F` is `../` in disguise, and
+ * `foldSegments` is the only thing that refuses a chain climbing out of the
+ * content root.
+ *
+ * Exported for `route-path.ts`, which needs the decode without the split:
+ * an alias may carry a literal `#` or `?` — `c# guide` is a page name — and
+ * {@link splitHref} would cut the string there and throw the rest away.
+ */
+declare function decodePath(path: string, href: string): string;
+/**
+ * An href, split at `?` and `#`, with the path decoded and the rest left alone.
+ *
+ * ⚠️ ONE IMPLEMENTATION, BECAUSE THE THIRD COPY WAS WRONG. Four call sites need
+ * this exact sequence — split, decode the path, fold, re-attach — and three of
+ * them had it inline while `foldImageSrc` in `render.ts` had none of it. An
+ * author dragging a file into GitHub's editor gets `![a](./getting%20started.png)`
+ * written for them, and that reached the resolver undecoded: `readFile` on a
+ * filename with a literal `%20` in it, `ENOENT`, and a build failed on an image
+ * that is plainly on disk and that GitHub renders. `./diagram.png?v=2` and
+ * `./sprite.svg#icon` baked the query and the fragment into the filename the
+ * same way.
+ *
+ * A query and a fragment are never decoded: `?q=a%26b` carries a literal
+ * ampersand that decoding would turn into a separator, and neither is part of
+ * any filename.
+ */
+interface HrefParts {
+  /** Path, percent-decoded and NFC-normalised — what {@link foldSegments} needs. */
+  path: string;
+  /**
+   * The same span exactly as authored.
+   *
+   * One caller needs it: {@link normalizeInternalRoute} strips `basePath` off
+   * the front by length, and doing that to a decoded path would cut at the
+   * wrong offset for any href that percent-encoded part of the prefix.
+   */
+  rawPath: string;
+  /** `?query` as authored, or `''`. */
+  query: string;
+  /** `#hash` as authored, or `''`. */
+  hash: string;
+}
+/**
+ * Split an href into its path, query and fragment; decode only the path.
+ *
+ * Throws a {@link URIError} if the path is not valid percent-encoding, with the
+ * whole href in the message — see {@link decodeSegment}.
+ */
+declare function splitHref(href: string): HrefParts;
 /**
  * The built-in {@link LinkResolver}: markdown file path in, route out.
  *
@@ -71,4 +153,4 @@ declare function resolveMarkdownLink(href: string, fromDir: readonly string[], b
  */
 declare const remarkDocLinks: Plugin<[RemarkDocLinksOptions], Root>;
 //#endregion
-export { type DocLinkContext, DocLinkRef, RemarkDocLinksOptions, foldSegments, remarkDocLinks, resolveMarkdownLink };
+export { type DocLinkContext, DocLinkRef, HrefParts, RemarkDocLinksOptions, decodePath, foldSegments, isRootMount, remarkDocLinks, resolveMarkdownLink, splitHref };