@waveso/docs 0.2.0 → 0.4.0

package/dist/render.js

@@ -1,10 +1,11 @@
 import { docsError } from "./docs-error.js";
 import { DEFAULT_DOCS_THEMES, createDocsHighlighter } from "./highlighter.js";
 import { rehypeCaptureToc } from "./plugins/rehype-capture-toc.js";
+import { rehypeCodeFrame } from "./plugins/rehype-code-frame.js";
 import { rehypeNormalizeCodeLanguage, rehypeRestoreExcludedCode } from "./plugins/rehype-code-language.js";
 import { rehypeFallbackHeadingIds } from "./plugins/rehype-fallback-heading-ids.js";
 import { rehypeFlattenRoots } from "./plugins/rehype-flatten-roots.js";
-import { foldSegments, remarkDocLinks } from "./plugins/remark-doc-links.js";
+import { foldSegments, remarkDocLinks, resolveMarkdownLink } from "./plugins/remark-doc-links.js";
 import { remarkUnwrapImages } from "./plugins/remark-unwrap-images.js";
 import { remarkYouTube } from "./plugins/remark-youtube.js";
 import rehypeShikiFromHighlighter from "@shikijs/rehype/core";
@@ -145,7 +146,7 @@ function titleHeadingNode(title) {
 *
 * The tree is the payload: it crosses the RSC boundary, so every byte is
 * shipped to every reader.
-* Positions are 38% of that JSON on a typical page — line and column offsets
+* Positions are roughly a third of that JSON — line and column offsets
 * into a markdown file the browser does not have and cannot fetch. Nothing
 * downstream reads them: link errors are reported from positions captured
 * during the mdast phase, and the TOC works off ids.
@@ -188,28 +189,48 @@ function stripPositions(tree) {
 *  8. `rehypeFallbackHeadingIds` — before slugging, so an emoji-only heading
 *                             never seeds the collision counter with `''`.
 *  9. `rehypeSlug`          — assigns heading ids.
-* 10. `rehypeCaptureToc`    — reads those ids. Before autolinking, so heading
-*                             text is captured without the appended `#`.
-* 11. `rehypeAutolinkHeadings` — appends the permalink.
+* 10. `rehypeAutolinkHeadings` — appends the permalink.
+* 11. `rehypePlugins`      — the consumer's, after slugging and autolinking so
+*                             heading ids exist, and before the code steps so
+*                             a `<pre>` is still the author's text.
 * 12. `rehypeNormalizeCodeLanguage` — immediately before Shiki, which is the
 *                             last moment `class="language-JSON"` exists.
-* 13. `rehypeShikiFromHighlighter` — near-last: it replaces `<pre><code>`
+* 13. `rehypeCodeFrame`    — the one step wide window: after 12, which folds
+*                             the language and disguises excluded fences, and
+*                             before Shiki, which destroys `code.data.meta`
+*                             and with it the fence's `title="…"`.
+* 14. `rehypeShikiFromHighlighter` — near-last: it replaces `<pre><code>`
 *                             wholesale, and anything walking code blocks
 *                             afterwards would be walking Shiki's token spans.
-* 14. `rehypeRestoreExcludedCode` — the other side of step 12's disguise.
-* 15. `rehypeFlattenRoots` — last of all, because Shiki is what splices a
-*                             `root` into `root.children` and the published
+* 15. `rehypeRestoreExcludedCode` — the other side of step 12's disguise.
+* 16. `rehypeFlattenRoots` — because Shiki is what splices a `root` into
+*                             `root.children` and the published
 *                             `RenderedDoc.hast` type says that cannot happen.
+*                             Step 13 is the first thing to put a `root`
+*                             inside an *element* rather than at the top, so
+*                             this recursing into element children is now
+*                             load-bearing rather than defensive.
+* 17. `rehypeCaptureToc`    — DEAD LAST, and that is the design rather than an
+*                             ordering detail. The TOC is then read off the
+*                             identical tree `extractSearchRecords` walks, so
+*                             a consumer plugin cannot put the two out of step
+*                             — and no validation pass or error has to exist
+*                             to notice when it does. Measured both drifts
+*                             before the move: a plugin deleting a heading id
+*                             left `toc` pointing at an id no longer in the
+*                             DOM while search silently dropped the section;
+*                             one adding an `<h2>` produced a search record
+*                             with no TOC entry. Both silent.
 */
 async function buildProcessor(options, themes, highlighterPromise) {
 	const highlighter = await highlighterPromise;
-	return unified().use(remarkParse).use(remarkGfm).use(remarkDocLinks, {
+	return unified().use(remarkParse).use(remarkGfm).use(options.remarkPlugins ?? []).use(remarkDocLinks, {
 		basePath: options.config.basePath,
 		...options.linkResolver === void 0 ? {} : { resolve: options.linkResolver }
 	}).use(remarkUnwrapImages).use(remarkYouTube).use(remarkRehype, {
 		allowDangerousHtml: false,
 		footnoteLabelProperties: { className: ["wave-docs-sr-only"] }
-	}).use(rehypeGithubAlerts, { build: buildCallout }).use(rehypeFallbackHeadingIds).use(rehypeSlug).use(rehypeCaptureToc).use(rehypeAutolinkHeadings, {
+	}).use(rehypeGithubAlerts, { build: buildCallout }).use(rehypeFallbackHeadingIds).use(rehypeSlug).use(rehypeAutolinkHeadings, {
 		behavior: "append",
 		content: HEADING_ANCHOR_CONTENT,
 		properties: {
@@ -217,13 +238,13 @@ async function buildProcessor(options, themes, highlighterPromise) {
 			ariaHidden: "true",
 			tabIndex: -1
 		}
-	}).use(rehypeNormalizeCodeLanguage, { ...options.excludeLangs === void 0 ? {} : { exclude: options.excludeLangs } }).use(rehypeShikiFromHighlighter, highlighter, {
+	}).use(options.rehypePlugins ?? []).use(rehypeNormalizeCodeLanguage, { ...options.excludeLangs === void 0 ? {} : { exclude: options.excludeLangs } }).use(rehypeCodeFrame).use(rehypeShikiFromHighlighter, highlighter, {
 		themes,
 		defaultColor: false,
 		fallbackLanguage: "text",
 		defaultLanguage: "text",
 		addLanguageClass: true
-	}).use(rehypeRestoreExcludedCode).use(rehypeFlattenRoots).freeze();
+	}).use(rehypeRestoreExcludedCode).use(rehypeFlattenRoots).use(rehypeCaptureToc).freeze();
 }
 /**
 * Create a renderer.
@@ -338,4 +359,4 @@ function createDocsRenderer(options) {
 	} };
 }
 //#endregion
-export { createDocsRenderer };
+export { createDocsRenderer, resolveMarkdownLink };

package/dist/route-path.d.ts

@@ -0,0 +1,46 @@
+//#region src/route-path.d.ts
+/**
+ * Turning route segments into a URL path.
+ *
+ * Private — deliberately not an entry point in `package.json`. `toAliasRoute`
+ * was exported from `./source` and therefore public, which froze both its
+ * signature and the wording of three error messages under semver, for a
+ * function no README mentions and only this package calls. It lives here with
+ * `encodeSegments` because the two have to agree: an alias and a link that
+ * spell the same page differently produce a redirect no request can match.
+ */
+/**
+ * Percent-encode the segments, and only here.
+ *
+ * `segments` and `slug` stay raw on purpose: Next decodes route params before
+ * they reach `find()`, so an encoded slug would match nothing. Unencoded, a
+ * `#`, `?` or `%` in a filename stops being part of the path — the sitemap
+ * emitted `https://example.com/docs/c#%20guide`, and `alternates.canonical`
+ * and `og:url` are built by the same call — while a space produced a URL that
+ * only works until something re-encodes it.
+ */
+declare function encodeSegments(segments: readonly string[]): string;
+/**
+ * A former URL from `aliases` frontmatter, as a route.
+ *
+ * `'quickstart'` on a site mounted at `/docs` becomes `/docs/quickstart`.
+ * Leading and trailing slashes are tolerated because authors write them, but
+ * the value is always relative to the base path — an alias of `'/docs/old'` on
+ * a `/docs` site would produce `/docs/docs/old`.
+ *
+ * Shared by both adapters so they agree on which routes exist: an alias is a
+ * redirect the host installs, so a link to one resolves, and a link that
+ * builds under Next must build under Vite. The source scan calls it too, so
+ * every rejection below names the markdown file at the moment it is read.
+ */
+declare function toAliasRoute(alias: string, basePath: string,
+/**
+ * The source path, for the error. A STRING rather than the whole `DocFile`
+ * it used to take: this function dereferenced exactly one property of it, and
+ * demanding the object meant a cache reader or a manifest-driven redirect
+ * table had to fabricate a `DocFile` to agree with the package about which
+ * routes exist. That is the reason it is exported at all.
+ */
+sourceLabel: string): string;
+//#endregion
+export { encodeSegments, toAliasRoute };

package/dist/route-path.js

@@ -0,0 +1,51 @@
+import { docsError } from "./docs-error.js";
+import { foldSegments } from "./plugins/remark-doc-links.js";
+//#region src/route-path.ts
+/**
+* Turning route segments into a URL path.
+*
+* Private — deliberately not an entry point in `package.json`. `toAliasRoute`
+* was exported from `./source` and therefore public, which froze both its
+* signature and the wording of three error messages under semver, for a
+* function no README mentions and only this package calls. It lives here with
+* `encodeSegments` because the two have to agree: an alias and a link that
+* spell the same page differently produce a redirect no request can match.
+*/
+/**
+* Percent-encode the segments, and only here.
+*
+* `segments` and `slug` stay raw on purpose: Next decodes route params before
+* they reach `find()`, so an encoded slug would match nothing. Unencoded, a
+* `#`, `?` or `%` in a filename stops being part of the path — the sitemap
+* emitted `https://example.com/docs/c#%20guide`, and `alternates.canonical`
+* and `og:url` are built by the same call — while a space produced a URL that
+* only works until something re-encodes it.
+*/
+function encodeSegments(segments) {
+	return segments.map(encodeURIComponent).join("/");
+}
+const ALIAS_PATTERN_CHARS = /[:()+*?{}]/;
+/**
+* A former URL from `aliases` frontmatter, as a route.
+*
+* `'quickstart'` on a site mounted at `/docs` becomes `/docs/quickstart`.
+* Leading and trailing slashes are tolerated because authors write them, but
+* the value is always relative to the base path — an alias of `'/docs/old'` on
+* a `/docs` site would produce `/docs/docs/old`.
+*
+* Shared by both adapters so they agree on which routes exist: an alias is a
+* redirect the host installs, so a link to one resolves, and a link that
+* builds under Next must build under Vite. The source scan calls it too, so
+* every rejection below names the markdown file at the moment it is read.
+*/
+function toAliasRoute(alias, basePath, sourceLabel) {
+	const trimmed = alias.trim();
+	if (trimmed.split("/").some((part) => part === "." || part === "..")) throw docsError("invalid-alias", `@waveso/docs: the alias '${alias}' in ${sourceLabel} has a '.' or '..' segment. An alias is a former URL relative to the docs base path, not a path on disk: write \`aliases: [legacy/old-name]\`.`);
+	const pattern = ALIAS_PATTERN_CHARS.exec(trimmed);
+	if (pattern !== null) throw docsError("invalid-alias", `@waveso/docs: the alias '${alias}' in ${sourceLabel} contains '${pattern[0]}', which Next compiles as redirect pattern syntax rather than as part of the URL — the redirect then swallows every page whose route the pattern happens to match, or fails the build. Remove the character; an alias is a literal former URL.`);
+	const segments = foldSegments([], trimmed);
+	if (segments === void 0 || segments.length === 0) throw docsError("invalid-alias", `@waveso/docs: ${sourceLabel} has an empty entry in its \`aliases\` frontmatter. Each alias is a former URL for this page, relative to the docs base path — e.g. \`aliases: [quickstart]\`.`);
+	return `${basePath}/${encodeSegments(segments)}`;
+}
+//#endregion
+export { encodeSegments, toAliasRoute };

package/dist/search-index.d.ts

@@ -35,10 +35,11 @@ declare function extractSearchRecords(doc: RenderedDoc): SearchRecord[];
 /**
  * Build a serialised MiniSearch index from extracted records.
  *
- * The return value is JSON, ready for `MiniSearch.loadJSON` on the client or
- * for {@link writeSearchIndex} to put on disk. The output is byte-stable for a
- * given record list, so an index committed to the repository does not dirty
- * the diff on every build.
+ * The return value is JSON, ready for `MiniSearch.loadJSON` on the client.
+ * `docs.searchIndex` serves exactly this; reach for `buildSearchIndex`
+ * directly only when you need an artifact that route cannot produce. The
+ * output is byte-stable for a given record list, which is what lets the
+ * route ship a strong `ETag`.
  *
  * ⚠️ `options` MUST ALSO REACH THE DIALOG — pass the identical object to
  * `SearchDialog`'s `searchOptions`. Both sides feed it through
@@ -47,23 +48,5 @@ declare function extractSearchRecords(doc: RenderedDoc): SearchRecord[];
  * spell: zero results, no error, nothing in the console.
  */
 declare function buildSearchIndex(records: SearchRecord[], options?: Partial<Options<SearchRecord>>): string;
-/**
- * Write the serialised index to `outFile`, creating parent directories.
- *
- * Returns the byte size written, so a build step can log it or assert a
- * budget — a docs index that quietly crosses a megabyte is a regression
- * nobody notices until the dialog takes a second to open.
- *
- * ⚠️ WRITTEN BESIDE THE TARGET AND RENAMED OVER IT, NEVER INTO IT. The target
- * is normally `public/search-index.json`, a live static asset: writing in
- * place truncates it to zero and grows it back in 1 MiB chunks, and a fetch
- * landing in that window gets a 200 with a half-written body. `response.ok`
- * passes, the parse throws, and the dialog is stuck in its error state —
- * *"Try reloading the page"* — for every visitor, reloading forever, until
- * someone redeploys content that did not change. `rename` is atomic within a
- * filesystem, so a reader sees either the whole old file or the whole new one;
- * it also makes two concurrent builds safe.
- */
-declare function writeSearchIndex(records: SearchRecord[], outFile: string, options?: Partial<Options<SearchRecord>>): Promise<number>;
 //#endregion
-export { buildSearchIndex, extractSearchRecords, writeSearchIndex };
+export { buildSearchIndex, extractSearchRecords };

package/dist/search-index.js

@@ -1,22 +1,7 @@
 import { isFootnotes, isTransparentContainer } from "./section-boundary.js";
 import { mergeSearchOptions } from "./search-options.js";
-import { mkdir, rename, rm, writeFile } from "node:fs/promises";
-import path from "node:path";
 import MiniSearch from "minisearch";
 //#region src/search-index.ts
-/**
-* Build-time search index construction.
-*
-* Node-only, and deliberately so: the markdown parser, the hast walk and
-* MiniSearch's index builder all run once per build, and the browser receives
-* nothing but the serialised result. `src/react/search-dialog.tsx` is the
-* matching client half.
-*
-* MiniSearch over Fuse.js is a measured choice, not a taste one: on a 282-page
-* corpus Fuse ran 96.6 ms median / 298 ms max per query against MiniSearch's
-* 1.35 ms / 3.84 ms. Fuse is a fuzzy short-string matcher routinely
-* misapplied to full text.
-*/
 /** `<h1>`…`<h6>` to their numeric depth. */
 const HEADING_DEPTHS = /* @__PURE__ */ new Map([
 	["h1", 1],
@@ -217,10 +202,11 @@ function collapseWhitespace(text) {
 /**
 * Build a serialised MiniSearch index from extracted records.
 *
-* The return value is JSON, ready for `MiniSearch.loadJSON` on the client or
-* for {@link writeSearchIndex} to put on disk. The output is byte-stable for a
-* given record list, so an index committed to the repository does not dirty
-* the diff on every build.
+* The return value is JSON, ready for `MiniSearch.loadJSON` on the client.
+* `docs.searchIndex` serves exactly this; reach for `buildSearchIndex`
+* directly only when you need an artifact that route cannot produce. The
+* output is byte-stable for a given record list, which is what lets the
+* route ship a strong `ETag`.
 *
 * ⚠️ `options` MUST ALSO REACH THE DIALOG — pass the identical object to
 * `SearchDialog`'s `searchOptions`. Both sides feed it through
@@ -233,36 +219,5 @@ function buildSearchIndex(records, options = {}) {
 	index.addAll(records);
 	return JSON.stringify(index);
 }
-/**
-* Write the serialised index to `outFile`, creating parent directories.
-*
-* Returns the byte size written, so a build step can log it or assert a
-* budget — a docs index that quietly crosses a megabyte is a regression
-* nobody notices until the dialog takes a second to open.
-*
-* ⚠️ WRITTEN BESIDE THE TARGET AND RENAMED OVER IT, NEVER INTO IT. The target
-* is normally `public/search-index.json`, a live static asset: writing in
-* place truncates it to zero and grows it back in 1 MiB chunks, and a fetch
-* landing in that window gets a 200 with a half-written body. `response.ok`
-* passes, the parse throws, and the dialog is stuck in its error state —
-* *"Try reloading the page"* — for every visitor, reloading forever, until
-* someone redeploys content that did not change. `rename` is atomic within a
-* filesystem, so a reader sees either the whole old file or the whole new one;
-* it also makes two concurrent builds safe.
-*/
-async function writeSearchIndex(records, outFile, options = {}) {
-	const json = buildSearchIndex(records, options);
-	const absolute = path.resolve(outFile);
-	const temporary = `${absolute}.tmp-${process.pid}`;
-	await mkdir(path.dirname(absolute), { recursive: true });
-	try {
-		await writeFile(temporary, json, "utf8");
-		await rename(temporary, absolute);
-	} catch (error) {
-		await rm(temporary, { force: true });
-		throw error;
-	}
-	return Buffer.byteLength(json, "utf8");
-}
 //#endregion
-export { buildSearchIndex, extractSearchRecords, writeSearchIndex };
+export { buildSearchIndex, extractSearchRecords };

package/dist/sitemap-limit.d.ts

@@ -0,0 +1,34 @@
+//#region src/sitemap-limit.d.ts
+/**
+ * Google's per-sitemap URL cap, and the warning for crossing it.
+ *
+ * Private — deliberately not an entry point in `package.json`. It lives in its
+ * own module for one reason: the branch is otherwise untestable. `next.ts` held
+ * the limit and the `console.warn` inline, and reaching them from a test meant
+ * writing 50,001 markdown files to a temporary directory, so the test that
+ * claimed to cover it ("warns rather than silently emitting an oversized
+ * sitemap") built a one-page site and asserted the warning did *not* fire. It
+ * could only ever fail if the comparison were inverted.
+ *
+ * A count is the whole input. Split out, the arithmetic and the wording are
+ * checkable in microseconds, and `createDocsSitemap`'s own test keeps covering
+ * the case that matters at the integration level: an ordinary sitemap stays
+ * quiet.
+ */
+/**
+ * The cap.
+ *
+ * 50,000 URLs or 50 MB uncompressed, whichever comes first; a crawler rejects
+ * the file whole rather than truncating it.
+ */
+declare const SITEMAP_URL_LIMIT = 50000;
+/**
+ * The warning for a sitemap of `count` URLs, or `undefined` when it fits.
+ *
+ * Splitting belongs to the caller — Next's `generateSitemaps` plus a slice of
+ * the returned array is three lines — but silently emitting a file no crawler
+ * will read is not something to discover from Search Console six weeks later.
+ */
+declare function sitemapLimitWarning(count: number): string | undefined;
+//#endregion
+export { SITEMAP_URL_LIMIT, sitemapLimitWarning };

package/dist/sitemap-limit.js

@@ -0,0 +1,37 @@
+//#region src/sitemap-limit.ts
+/**
+* Google's per-sitemap URL cap, and the warning for crossing it.
+*
+* Private — deliberately not an entry point in `package.json`. It lives in its
+* own module for one reason: the branch is otherwise untestable. `next.ts` held
+* the limit and the `console.warn` inline, and reaching them from a test meant
+* writing 50,001 markdown files to a temporary directory, so the test that
+* claimed to cover it ("warns rather than silently emitting an oversized
+* sitemap") built a one-page site and asserted the warning did *not* fire. It
+* could only ever fail if the comparison were inverted.
+*
+* A count is the whole input. Split out, the arithmetic and the wording are
+* checkable in microseconds, and `createDocsSitemap`'s own test keeps covering
+* the case that matters at the integration level: an ordinary sitemap stays
+* quiet.
+*/
+/**
+* The cap.
+*
+* 50,000 URLs or 50 MB uncompressed, whichever comes first; a crawler rejects
+* the file whole rather than truncating it.
+*/
+const SITEMAP_URL_LIMIT = 5e4;
+/**
+* The warning for a sitemap of `count` URLs, or `undefined` when it fits.
+*
+* Splitting belongs to the caller — Next's `generateSitemaps` plus a slice of
+* the returned array is three lines — but silently emitting a file no crawler
+* will read is not something to discover from Search Console six weeks later.
+*/
+function sitemapLimitWarning(count) {
+	if (count <= 5e4) return void 0;
+	return `@waveso/docs: this sitemap has ${count} URLs, above Google's limit of ${SITEMAP_URL_LIMIT}. Split it with Next's \`generateSitemaps\` and slice the array this returns.`;
+}
+//#endregion
+export { SITEMAP_URL_LIMIT, sitemapLimitWarning };

package/dist/source.d.ts

@@ -53,27 +53,5 @@ declare function resolveDocsConfig<TFrontmatter extends DocFrontmatter = DocFron
  * Create (or reuse) the source for a content directory.
  */
 declare function createDocsSource<TFrontmatter extends DocFrontmatter = DocFrontmatter>(config: DocsConfig<TFrontmatter>): DocsSource<TFrontmatter>;
-/**
- * A former URL from `aliases` frontmatter, as a route.
- *
- * `'quickstart'` on a site mounted at `/docs` becomes `/docs/quickstart`.
- * Leading and trailing slashes are tolerated because authors write them, but
- * the value is always relative to the base path — an alias of `'/docs/old'` on
- * a `/docs` site would produce `/docs/docs/old`.
- *
- * Shared by both adapters so they agree on which routes exist: an alias is a
- * redirect the host installs, so a link to one resolves, and a link that
- * builds under Next must build under Vite. The source scan calls it too, so
- * every rejection below names the markdown file at the moment it is read.
- */
-declare function toAliasRoute(alias: string, basePath: string,
-/**
- * The source path, for the error. A STRING rather than the whole `DocFile`
- * it used to take: this function dereferenced exactly one property of it, and
- * demanding the object meant a cache reader or a manifest-driven redirect
- * table had to fabricate a `DocFile` to agree with the package about which
- * routes exist. That is the reason it is exported at all.
- */
-sourceLabel: string): string;
 //#endregion
-export { DocsSource, createDocsSource, resolveDocsConfig, toAliasRoute };
+export { DocsSource, createDocsSource, resolveDocsConfig };

package/dist/source.js

@@ -1,10 +1,11 @@
 import { docsError } from "./docs-error.js";
 import { parseFrontmatter } from "./frontmatter.js";
 import { orderNavEntries, readDocsMeta } from "./meta.js";
-import { foldSegments } from "./plugins/remark-doc-links.js";
+import { encodeSegments, toAliasRoute } from "./route-path.js";
 import { readFile, readdir, realpath, stat } from "node:fs/promises";
 import path from "node:path";
-import matter from "gray-matter";
+import { VFile } from "vfile";
+import { matter } from "vfile-matter";
 //#region src/source.ts
 /** Markdown only. MDX is deliberately out of scope for this package. */
 const PAGE_EXTENSION = ".md";
@@ -20,7 +21,11 @@ const INDEX_NAME = "index";
 */
 function resolveDocsConfig(config) {
 	return {
-		contentDir: path.resolve(process.cwd(), config.contentDir),
+		contentDir: path.resolve(
+			/*turbopackIgnore: true*/
+			process.cwd(),
+			config.contentDir
+		),
 		basePath: normalizeBasePath(config.basePath ?? "/docs"),
 		includeDrafts: config.includeDrafts ?? false,
 		assertLinks: config.assertLinks ?? true,
@@ -87,6 +92,33 @@ function buildSource(config) {
 	const isVisible = (file) => config.includeDrafts || file.frontmatter.draft !== true;
 	return {
 		config,
+		/**
+		* Throw the scan away. The next query reads the disk again.
+		*
+		* ⚠️ A STAT-WALK DIRTY CHECK WAS BUILT HERE AND MEASURED AND REMOVED. The
+		* idea is obvious and the roadmap called for it: mark dirty, then compare
+		* a stat-only fingerprint of the tree against the cached one and skip the
+		* re-read when nothing changed. It rests on stat being much cheaper than
+		* read, and on this corpus it is not — the fingerprint has to `readdir`
+		* every directory and `stat` every file, which is nearly everything the
+		* scan does apart from the read and the parse.
+		*
+		* Measured over 501 pages, median of six, against a full rescan:
+		*
+		*   ~1.4 KB pages   28.3 ms vs 26.8 ms   0.95x  (slower)
+		*   ~20 KB pages    28.8 ms vs 27.4 ms   0.95x  (slower)
+		*   ~120 KB pages   39.1 ms vs 45.1 ms   1.15x  (faster)
+		*
+		* Documentation pages are the first two rows. So it is a small regression
+		* plus a new class of invalidation bug, in exchange for a win on a corpus
+		* nobody has. There is no cheaper correct fingerprint either: statting
+		* only directories catches an added or renamed file but not an edited one,
+		* which is the common case in a dev server.
+		*
+		* If this is ever revisited, the thing to change is the *scan*, not the
+		* check — patch only the files whose mtime moved and re-derive the nav in
+		* memory, which is a different item with a much harder correctness story.
+		*/
 		invalidate() {
 			cached = null;
 		},
@@ -201,9 +233,10 @@ async function readPage(filePath, name, dirSegments, config) {
 	let data;
 	let content;
 	try {
-		const parsed = matter(raw, { language: "yaml" });
-		data = parsed.data;
-		content = parsed.content;
+		const file = new VFile({ value: raw.charCodeAt(0) === 65279 ? raw.slice(1) : raw });
+		matter(file, { strip: true });
+		data = file.data.matter;
+		content = String(file);
 	} catch (err) {
 		const reason = err instanceof Error ? err.message : String(err);
 		throw docsError("invalid-frontmatter", `Could not parse the frontmatter block in ${relativePath}: ${reason}`, { cause: err });
@@ -348,29 +381,6 @@ function isVisibleIn(file, config) {
 * it. `c++` is the loud sibling: the build aborts with `Unexpected MODIFIER at
 * 7`, naming an offset into a string the author never wrote and no file.
 */
-const ALIAS_PATTERN_CHARS = /[:()+*?{}]/;
-/**
-* A former URL from `aliases` frontmatter, as a route.
-*
-* `'quickstart'` on a site mounted at `/docs` becomes `/docs/quickstart`.
-* Leading and trailing slashes are tolerated because authors write them, but
-* the value is always relative to the base path — an alias of `'/docs/old'` on
-* a `/docs` site would produce `/docs/docs/old`.
-*
-* Shared by both adapters so they agree on which routes exist: an alias is a
-* redirect the host installs, so a link to one resolves, and a link that
-* builds under Next must build under Vite. The source scan calls it too, so
-* every rejection below names the markdown file at the moment it is read.
-*/
-function toAliasRoute(alias, basePath, sourceLabel) {
-	const trimmed = alias.trim();
-	if (trimmed.split("/").some((part) => part === "." || part === "..")) throw docsError("invalid-alias", `@waveso/docs: the alias '${alias}' in ${sourceLabel} has a '.' or '..' segment. An alias is a former URL relative to the docs base path, not a path on disk: write \`aliases: [legacy/old-name]\`.`);
-	const pattern = ALIAS_PATTERN_CHARS.exec(trimmed);
-	if (pattern !== null) throw docsError("invalid-alias", `@waveso/docs: the alias '${alias}' in ${sourceLabel} contains '${pattern[0]}', which Next compiles as redirect pattern syntax rather than as part of the URL — the redirect then swallows every page whose route the pattern happens to match, or fails the build. Remove the character; an alias is a literal former URL.`);
-	const segments = foldSegments([], trimmed);
-	if (segments === void 0 || segments.length === 0) throw docsError("invalid-alias", `@waveso/docs: ${sourceLabel} has an empty entry in its \`aliases\` frontmatter. Each alias is a former URL for this page, relative to the docs base path — e.g. \`aliases: [quickstart]\`.`);
-	return `${basePath}/${encodeSegments(segments)}`;
-}
 /**
 * ⚠️ `_` AND `.` BOTH, MATCHING `isIgnoredDir` BELOW — which is what this did
 * NOT do. A leading dot was skipped and a leading underscore was not, so
@@ -394,19 +404,6 @@ function isIgnoredDir(name) {
 function stripExtension(name) {
 	return name.slice(0, name.length - path.extname(name).length);
 }
-/**
-* Percent-encode the segments, and only here.
-*
-* `segments` and `slug` stay raw on purpose: Next decodes route params before
-* they reach `find()`, so an encoded slug would match nothing. Unencoded, a
-* `#`, `?` or `%` in a filename stops being part of the path — the sitemap
-* emitted `https://example.com/docs/c#%20guide`, and `alternates.canonical`
-* and `og:url` are built by the same call — while a space produced a URL that
-* only works until something re-encodes it.
-*/
-function encodeSegments(segments) {
-	return segments.map(encodeURIComponent).join("/");
-}
 function toHref(basePath, segments) {
 	if (segments.length === 0) return basePath === "" ? "/" : basePath;
 	return `${basePath}/${encodeSegments(segments)}`;
@@ -425,4 +422,4 @@ function humanize(name) {
 	return name.split(/[-_\s]+/).filter((word) => word !== "").map((word) => `${word.charAt(0).toUpperCase()}${word.slice(1)}`).join(" ");
 }
 //#endregion
-export { createDocsSource, resolveDocsConfig, toAliasRoute };
+export { createDocsSource, resolveDocsConfig };