@waveso/docs 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,102 @@
 # @waveso/docs
 
+## 0.6.0
+
+### Minor Changes
+
+- 633f274: **Anchors are checked now.** A route was verified and its fragment thrown away, so `[setup](./install.md#setup)` built green with no `#setup` anywhere on the page. It is the more common of the two link failures — headings get renamed constantly and nothing renames the links into them — and it went unchecked while the rarer one did not.
+
+  `onBrokenAnchors` defaults to `'throw'`, and the error names the heading you probably meant:
+
+  ```
+  @waveso/docs: guide.md:12 links to '#instalation', and this page has no
+  '#instalation'. Did you mean 'installation'?
+  ```
+
+  Checked against every `id` in the rendered page, not against the table of contents — which captures `h2`–`h3` only, so a link to an `h4` is fine, and so is a link to an id one of your `rehypePlugins` added. Same-page anchors are checked as each page renders, so those errors carry a line number; cross-page anchors need the target's ids and are checked by `docs.renderAll()`, which runs in every build that serves search.
+
+  **`onUnverifiableLinks` is replaced by `externalRoutes`, and the default flipped.** It shipped in no release, so nothing to migrate.
+
+  The old option asked you to reason about _our_ inability to verify a link. The new one asks for a fact about _your_ application, which is the thing you actually know:
+
+  ```ts
+  createDocsRoute({
+    basePath: "/",
+    externalRoutes: ["/login", "/dashboard", "/api/"],
+  });
+  ```
+
+  And absolute links at a root mount are now checked by default rather than ignored. A root mount is what you choose when the origin serves documentation and nothing else — `docs.example.com` — so an unknown absolute link there is a typo, and silence was the wrong default. A site that serves something else names what is its own; `/api` covers `/api/keys` and not `/apiary`.
+
+  That also removes the `'warn'` level that made no sense: warning on every legitimate route in your application is not a diagnostic.
+
+  **New error code `broken-anchor`**, documented in the troubleshooting table and offered in the bug form.
+
+- b6edd50: **New subpath `@waveso/docs/react/next-link`, exporting `DocsLink`** — `next/link` already adapted, so composing a shell by hand no longer needs a cast.
+
+  Passing `next/link` straight into `DocsSidebar` does not type-check under `exactOptionalPropertyTypes`: Next's `LinkProps` re-declares `onClick?`, `onMouseEnter?` and `onTouchStart?` _without_ `| undefined` while React's anchor props include it, so the two declaration files disagree over three props `next/link` accepts perfectly well at run time. It is a disagreement between dependencies, true of every `next/link` call site in a project with that flag on, and nothing the shape of `DocsLinkProps` can fix without breaking the plain-`<a>` fallback that keeps these components host-agnostic.
+
+  `docs.Layout` and `DocsSearch` have always absorbed it internally, so it only bit someone building their own shell — who was told in Troubleshooting to write `Link={Link as DocsLinkComponent}` and wait for a Next-wired component to ship. This is that component; the cast is retired and the note now shows the import.
+
+  ```tsx
+  "use client";
+  import { DocsLink } from "@waveso/docs/react/next-link";
+  import { DocsSidebar } from "@waveso/docs/react/sidebar";
+
+  <DocsSidebar nav={nav} pathname={pathname} Link={DocsLink} />;
+  ```
+
+  It carries `'use client'` — not for a hook, there is none, but because `DocsLink` is a function and a function cannot be handed from a Server Component to a Client one. Without the directive it would be a server reference and `next build` would refuse it, which is the same boundary this release fixed for MiniSearch options.
+
+  The private adapter factory it is built from is renamed `link-adapter.ts`, so the two are not one letter apart in the same directory. 180 bytes gzipped, with a 300-byte budget: it should stay the thinnest thing this package ships to a browser.
+
+- 1fa4317: **Link checking has severity levels, and broken links now say what you probably meant.**
+
+  **BREAKING: `assertLinks: boolean` is replaced by `onBrokenLinks: 'throw' | 'warn' | 'ignore'`**, defaulting to `'throw'`. `assertLinks: false` becomes `onBrokenLinks: 'ignore'`; `assertLinks: true` was the default and can be dropped. The shape follows Docusaurus's `onBrokenLinks` for the same reason it exists there: the tool cannot know how much a given site cares, and guessing produces either a build that fails on somebody's legitimate URL or one that ships a dead link quietly.
+
+  **Broken-link errors now offer the closest published route** when the link looks like a typo of one:
+
+  ```
+  @waveso/docs: guide.md:12 links to './instalation.md', which resolves to
+  '/docs/instalation' — no such page exists. Did you mean '/docs/installation'?
+  ```
+
+  A typo is a near-miss by construction, which is what makes the suggestion safe to offer _and_ safe to withhold — the same trick `git`, `tsc`, `cargo` and Python 3.12 use. It decorates an error that was already being raised; it never decides whether to raise one. `/docs/instructions` is five edits from `/docs/installation` — a different word, not a typo — and gets no suggestion, because sending an author to rename a correct link is worse than saying nothing.
+
+  **New `onUnverifiableLinks`, defaulting to `'ignore'`, closes the root-mount gap.** To check `[x](/setup)` the package must first know it is a documentation link. Under `basePath: '/docs'` the prefix says so. Under `basePath: '/'` there is no prefix — `/setup` may be a page of yours, `/login` almost certainly is — so until now those links were dropped unrecorded and a typo in one shipped silently.
+
+  They are recorded and marked now, and the site decides:
+
+  ```ts
+  createDocsRoute({
+    contentDir: "content/docs",
+    basePath: "/",
+    onUnverifiableLinks: "throw", // this domain is documentation and nothing else
+  });
+  ```
+
+  The default stays `'ignore'` because a root mount inside a larger application genuinely cannot distinguish the two, and failing that build would be wrong. Relative links (`./other.md`) are resolved against the content tree, so they are verifiable at every mount and always governed by `onBrokenLinks`.
+
+  `docs.wave.so` runs with `onUnverifiableLinks: 'throw'`, which is the configuration this option was written for.
+
+### Patch Changes
+
+- 102d6ae: **The README shows the live site instead of screenshots.** Three PNGs, a Playwright script to shoot them, a pinned tag and two tests to keep the pin honest — replaced by a link to [docs.wave.so](https://docs.wave.so), which is this package's documentation built with this package.
+
+  The screenshots were a photograph of the harness. The site _is_ the harness: the same `site/` that CI builds on every commit, whose acceptance test forbids it a single line of layout CSS of its own. A reader who wants to know what the shell looks like can now use it — open the search, resize to a phone, tab through the drawer — instead of looking at a picture of it taken on somebody's Mac.
+
+  It also removes a whole class of staleness. A pinned screenshot is wrong the moment the shell changes and right only if someone remembers to re-shoot and re-pin; the last one was pinned to `v0.3.0` while the images had been regenerated for 0.4.0, so npm showed a search dialog the release had already replaced. A URL cannot go stale.
+
+  `pnpm shoot` is gone. The regression it was meant to catch — a stylesheet change reflowing the shell — is the browser tier's, which asserts geometry rather than pixels and runs in the same Chromium everywhere.
+
+- e2bbaf4: **docs.wave.so serves the documentation at its root**, so a page is `docs.wave.so/installation` rather than `docs.wave.so/docs/installation` — a host called `docs` should not say it twice.
+
+  Nothing in the package changed: `basePath` has always taken any prefix, and `'/'` is one of them. The default is still `/docs`, defined in one place, and every consumer gets it unless they say otherwise.
+
+  What did change is which configuration the harnesses cover. `smoke/` builds on the default `/docs` in both output modes on every CI run, so moving the site to the root mount loses nothing and covers the half that was thin: an empty base path is a distinct code path in `toHref`, `toRoute` and `isInternalAbsoluteLink`, and two unit assertions used to be all of it. The two harnesses now cover both mount points and both documented layout shapes — smoke keeps the README's one-line `export default docs.Layout`, the site composes `<docs.Layout>` inside a root layout.
+
+  **One behaviour differs at the root mount, and it is worth knowing.** With an empty base, an absolute link like `/installation` cannot be told apart from any other route in the application, so it is not checked against the published routes — under `/docs`, a typo in `/docs/instalation` fails the build; at the root it does not. Relative markdown links, which is what documentation should be written with, are unaffected.
+
 ## 0.5.0
 
 ### Minor Changes

package/README.md

@@ -13,38 +13,11 @@
 
 <br />
 
-<!--
-  ⚠️ ABSOLUTE `raw.githubusercontent.com` URLS, PINNED TO A TAG.
-
-  npm rewrites relative markdown image paths onto its own CDN, but it does NOT
-  rewrite `<source srcset>` inside a `<picture>` — so a relative path here shows
-  a broken image on npmjs.com. And pinning to `main` rather than a tag means an
-  old version's README displays a future product: someone reading 0.3.0 in 2027
-  would see whatever the shell looks like then.
-
-  `pnpm shoot` regenerates these from the real site build. It is a LOCAL
-  command and CI deliberately does not run `pnpm shoot --check`: these PNGs are
-  compared byte for byte, and bytes do not survive a change of operating system
-  — the font stack resolves to SF Pro on the machine that shot them and to
-  DejaVu on a Linux runner, so every pixel of text differs and no tolerance
-  rescues glyphs that are different shapes. The regression that gate was meant
-  to catch — a stylesheet change reflowing the shell — is covered by the browser
-  tier, which asserts geometry rather than pixels in the same Chromium
-  everywhere. `scripts/shoot.ts` says the same at greater length.
--->
-<picture>
-  <source
-    media="(prefers-color-scheme: dark)"
-    srcset="https://raw.githubusercontent.com/wavedotso/wave-docs/v0.4.0/docs/media/hero-dark.png"
-  />
-  <img
-    src="https://raw.githubusercontent.com/wavedotso/wave-docs/v0.4.0/docs/media/hero-light.png"
-    alt="A documentation page rendered by @waveso/docs: a navigation sidebar, prose with syntax-highlighted code frames, and a table of contents."
-    width="100%"
-  />
-</picture>
-
-<p align="center"><em>The default page, with no CSS of your own. <a href="https://raw.githubusercontent.com/wavedotso/wave-docs/v0.4.0/docs/media/search.png">Search dialog →</a></em></p>
+<p align="center">
+  <strong><a href="https://docs.wave.so">docs.wave.so</a></strong> — the documentation for this package, built with this package.
+</p>
+
+<p align="center"><em>Every page you see there is markdown in <code>site/content/</code>, rendered by <code>docs.Layout</code> with no layout CSS of its own. It is the acceptance harness and the showcase, and it is the same build CI runs on every commit — so it cannot drift from what this README claims.</em></p>
 
 ---
 
@@ -225,6 +198,7 @@ Every component takes data as props, and two modules in `src/react/` import from
 | `DocsSidebar` | `react/sidebar` | Takes `pathname` as a prop, not from `next/navigation` |
 | `DocsToc` | `react/toc` | Scrollspy via `IntersectionObserver`. `label`, `topLabel`, `rootMargin`, `className` |
 | `DocsSearch` | `react/next-search` | `SearchDialog`, wired to Next's router. What you want |
+| `DocsLink` | `react/next-link` | `next/link`, adapted — pass it as `Link` when composing by hand |
 | `SearchDialog` | `react/search-dialog` | ⌘K, arrow keys, focus trap. Host-agnostic |
 | `Callout` | `react/callout` | Note · tip · important · warning · caution. `CALLOUT_TYPES` is the list |
 | `YouTube` | `react/youtube` | Click-to-load facade. `title`, `playLabel`, `hideLabel` — `{title}` interpolates the first |
@@ -233,7 +207,7 @@ Every component takes data as props, and two modules in `src/react/` import from
 
 `DocsToc`'s `rootMargin` is the `IntersectionObserver` margin that decides how far above the viewport a heading counts as current; the default keeps the highlight on the section you are reading rather than the one about to arrive. `topLabel` is the back-to-top link at the end.
 
-The two components the adapter injects take a little more than an `<a>` and an `<img>`. `DocsLinkProps` adds `prefetch` — passed straight to `next/link`, where `false` disables the hover and viewport paths both, so it is a stronger switch in the App Router than the name suggests. `DocsImageProps` adds `sizes`, `loading`, `decoding` and `fetchPriority`, forwarded to `next/image`; markdown carries none of them, so they come from your `imageResolver` or from a `components` override. `decoding` defaults to `async`, and `loading` to `lazy` — except on an image the author marked `eager`, which is usually the page's largest element.
+The two components the adapter injects take a little more than an `<a>` and an `<img>`. `DocsLinkProps` adds `prefetch` — passed straight to `next/link`, where `false` disables the hover and viewport paths both, so it is a stronger switch in the App Router than the name suggests. `DocsImageProps` carries `src`, `alt`, `width` and `height` — the four `next/image` refuses to render without — and adds `sizes`, `loading`, `decoding` and `fetchPriority`, forwarded to it; markdown carries none of them, so they come from your `imageResolver` or from a `components` override. `decoding` defaults to `async`, and `loading` to `lazy` — except on an image the author marked `eager`, which is usually the page's largest element.
 
 ### Layout
 
@@ -817,26 +791,61 @@ interface DocsConfig<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
   contentDir: string;        // relative paths resolve against process.cwd()
   basePath?: string;         // default '/docs'; '/' normalises to ''
   includeDrafts?: boolean;   // default false
-  assertLinks?: boolean;     // default true
+  onBrokenLinks?: DocsLinkSeverity;    // default 'throw'
+  onBrokenAnchors?: DocsLinkSeverity;  // default 'throw'
+  externalRoutes?: readonly string[];  // routes your app owns, not the docs
   frontmatterSchema?: StandardSchemaV1<unknown, TFrontmatter>;
 }
+
+type DocsLinkSeverity = 'throw' | 'warn' | 'ignore';
 ```
 
-`createDocsRoute` additionally accepts:
+### Broken links
 
-| Option | Default | Purpose |
-| --- | --- | --- |
-| `langs` | 18 grammars | Typed `readonly DocsLang[]`, so a typo is a compile error |
-| `themes` | `github-light` / `github-dark` | Shiki theme pair |
-| `highlighter` | built-in | Supply your own for grammars outside the set |
-| `titleHeading` | `true` | Build an `<h1>` from `frontmatter.title` when the markdown has none |
-| `components` | built-in map | Override any element → component mapping |
-| `siteUrl` | — | Makes canonical URLs absolute |
-| `linkResolver` · `imageResolver` | — | Override link rewriting and image dimensions. An `imageResolver` receives a folded, contained src — except an absolute `/logo.png` or a schemed `https://…`, which arrive unfolded, so branch on them |
+**`onBrokenLinks` defaults to `'throw'`, and should stay there.** A link that 404s was valid in your editor and on GitHub, so it is the kind of mistake nobody finds by reading — and a warning in a build log is a warning nobody reads. `'warn'` exists for a migration running knowingly against an incomplete corpus.
+
+The error names the file, the line and the closest published route when the link looks like a typo of one:
+
+```
+@waveso/docs: guide.md:12 links to './instalation.md', which resolves to
+'/docs/instalation' — no such page exists. Did you mean '/docs/installation'?
+Fix the link, or add an `aliases` entry to the page it used to point at.
+```
+
+A suggestion is offered only for a genuine near-miss. `/docs/instructions` is five edits from `/docs/installation` — a different word, not a typo — and gets none, because a wrong suggestion sends you to rename a link that was correct.
+
+### Broken anchors
+
+**`onBrokenAnchors` defaults to `'throw'`.** A route used to be verified and its fragment thrown away, so `[setup](./install.md#setup)` built green with no `#setup` anywhere on the page. It is the more common of the two failures: headings get renamed constantly, and nothing renames the links into them.
+
+```
+@waveso/docs: guide.md:12 links to '#instalation', and this page has no
+'#instalation'. Did you mean 'installation'? Heading ids come from the heading
+text, so renaming a heading renames its anchor.
+```
+
+Checked against every `id` in the rendered page rather than against the table of contents — which captures `h2`–`h3` only, so a link to an `h4` is fine, and so is a link to an id one of your `rehypePlugins` added. Lower it to `'warn'` if a plugin of yours adds ids this package cannot see at render time.
+
+Same-page anchors are checked as each page renders, so those errors carry the file and the line. Cross-page anchors need the target page's ids, which exist only once everything has been rendered — `docs.renderAll()` does that pass, and it runs in every build that serves search, because the index route is `force-static`.
 
-`titleHeading` defaults on because a document with no `h1` has a broken heading outline and fails every accessibility audit. Turn it off if your layout renders the title itself.
+### Routes your application owns
 
-The `<main>` always carries `id="docs-content"`, which is what `SkipLink` targets by default — there is no option to change it, because there was no matching option on `SkipLink` to follow it with, so changing it silently pointed the skip link at nothing. Outside `NODE_ENV=production` the content directory is always re-scanned per request; `docs.source.invalidate()` is the escape hatch if you need to force one.
+**`externalRoutes` only matters at a root mount.** Under `basePath: '/docs'` an absolute link either carries the prefix — so it is documentation and is checked — or it does not, and this package leaves it alone. Under `basePath: '/'` there is no prefix: `/setup` and `/login` look identical, and both are checked against the published pages.
+
+That is the right default, because a root mount is what you choose when the origin serves documentation and nothing else. If yours serves something else too, name what is yours:
+
+```ts
+// lib/docs-root.ts
+import { createDocsRoute } from '@waveso/docs/next';
+
+export const docs = createDocsRoute({
+  contentDir: 'content/docs',
+  basePath: '/',
+  externalRoutes: ['/login', '/dashboard', '/api/'],
+});
+```
+
+A link is skipped when it equals one of these or begins with one followed by `/` — so `/api` covers `/api/keys` and not `/apiary`. It is a statement about your application, so nothing here infers it.
 
 ### Translating the chrome
 
@@ -972,6 +981,7 @@ try {
 | `broken-link` | A markdown link resolves to a route no published page owns. | Fix the link, or add an `aliases` entry to the page that moved. |
 | `draft-link` | A link points at a page that exists but is `draft: true`. | Publish the page, or drop the link until it ships. |
 | `alias-link` | A link points at an alias, which is a redirect and not a page. | Link the page the alias redirects to — the error names it. |
+| `broken-anchor` | A `#fragment` that no heading on the target page owns. | Fix the link, or restore the heading. Heading ids come from the heading text, so renaming one renames its anchor. |
 | `invalid-alias` | An `aliases` entry is empty, escapes the content root, or is not URL-safe. | Write it as a root-relative path, e.g. `/docs/old-name`. |
 | `alias-collision` | Two pages claim one alias, or an alias shadows a real route. | Remove one of them; a redirect cannot have two destinations. |
 | `route-collision` | Two files resolve to the same route. | Usually `about.md` beside `about/index.md`. Keep one. |
@@ -1005,14 +1015,25 @@ ESM-only is forced rather than chosen: `unified` and the entire `remark-*` / `re
 If you extend the frontmatter schema, use `.exactOptional()` rather than `.optional()` for optional fields: the latter infers `{ description?: string | undefined }`, which is not assignable to `DocFrontmatter`.
 
 > [!NOTE]
-> Under `exactOptionalPropertyTypes: true`, passing `next/link` straight into
-> `DocsSidebar` does not type-check. Next's `LinkProps` re-declares `onClick?`,
-> `onMouseEnter?` and `onTouchStart?` *without* `| undefined`, and React's
+> Passing `next/link` **straight** into `DocsSidebar` does not type-check under
+> `exactOptionalPropertyTypes: true`. Next's `LinkProps` re-declares `onClick?`,
+> `onMouseEnter?` and `onTouchStart?` *without* `| undefined` while React's
 > anchor props include it, so the two declaration files disagree — about props
-> `next/link` accepts perfectly well at runtime. It is true of every
-> `next/link` call site in a project with that flag on, not just this one.
-> Cast at the call site (`Link={Link as DocsLinkComponent}`) until the
-> Next-wired navigation component ships.
+> `next/link` accepts perfectly well at runtime. It is true of every `next/link`
+> call site in a project with that flag on, not just this one.
+>
+> Import `DocsLink` instead of casting:
+>
+> ```tsx
+> 'use client';
+> import { DocsLink } from '@waveso/docs/react/next-link';
+> import { DocsSidebar } from '@waveso/docs/react/sidebar';
+>
+> <DocsSidebar nav={nav} pathname={pathname} Link={DocsLink} />
+> ```
+>
+> `docs.Layout` and `DocsSearch` have always used the same adapter internally,
+> so this only ever came up when composing a shell by hand.
 >
 > `docs.Page` and `DocsSearch` are both unaffected — each wraps `next/link`
 > inside the package, which is where that cast belongs. Without the flag,

package/dist/anchors.d.ts

@@ -0,0 +1,44 @@
+import { RenderedDoc } from "./types.js";
+import { Root } from "hast";
+//#region src/anchors.d.ts
+/**
+ * Every `id` in a tree, which is the set an anchor may target.
+ *
+ * Not the table of contents: that captures `h2`–`h3` only, so checking against
+ * it would reject a perfectly good link to an `h4` — and would miss an id a
+ * `rehypePlugins` entry put on something that is not a heading at all.
+ */
+declare function collectAnchorIds(tree: Root): Set<string>;
+/** An internal link carrying a fragment, as found in a rendered tree. */
+interface AnchorLink {
+  /** The href exactly as it stands in the tree, e.g. `/docs/install#setup`. */
+  href: string;
+  /** Route without the fragment. */
+  route: string;
+  /** Fragment without the `#`, percent-decoded. */
+  fragment: string;
+}
+/**
+ * `#fragment` split off an internal href, or `undefined`.
+ *
+ * Skips anything with a scheme and anything protocol-relative: an anchor on
+ * somebody else's page is theirs to get wrong, and a fragment there is a
+ * routine way to link into a spec.
+ */
+declare function splitAnchor(href: string): AnchorLink | undefined;
+/** Every internal anchor link in a tree, in document order. */
+declare function collectAnchorLinks(tree: Root): AnchorLink[];
+/**
+ * Cross-page anchors, once every page has been rendered.
+ *
+ * `report` is passed in rather than imported so this module stays free of the
+ * error factory and the severity plumbing — it answers "which anchors are
+ * wrong", and the caller owns what that costs.
+ *
+ * A link to a route nothing rendered is a *broken link*, not a broken anchor,
+ * and `assertLinks` has already reported it at its own severity. Skipped here
+ * so one mistake is not two failures.
+ */
+declare function assertAnchors(docs: ReadonlyArray<RenderedDoc<never>> | ReadonlyArray<RenderedDoc>, report: (from: string, link: AnchorLink, known: Set<string>) => void): void;
+//#endregion
+export { AnchorLink, assertAnchors, collectAnchorIds, collectAnchorLinks, splitAnchor };

package/dist/anchors.js

@@ -0,0 +1,76 @@
+import { visit } from "unist-util-visit";
+//#region src/anchors.ts
+/**
+* Every `id` in a tree, which is the set an anchor may target.
+*
+* Not the table of contents: that captures `h2`–`h3` only, so checking against
+* it would reject a perfectly good link to an `h4` — and would miss an id a
+* `rehypePlugins` entry put on something that is not a heading at all.
+*/
+function collectAnchorIds(tree) {
+	const ids = /* @__PURE__ */ new Set();
+	visit(tree, "element", (node) => {
+		const id = node.properties.id;
+		if (typeof id === "string" && id !== "") ids.add(id);
+	});
+	return ids;
+}
+/**
+* `#fragment` split off an internal href, or `undefined`.
+*
+* Skips anything with a scheme and anything protocol-relative: an anchor on
+* somebody else's page is theirs to get wrong, and a fragment there is a
+* routine way to link into a spec.
+*/
+function splitAnchor(href) {
+	if (href === "" || /^([a-z][a-z0-9+.-]*:|\/\/)/i.test(href)) return void 0;
+	const hash = href.indexOf("#");
+	if (hash === -1 || hash === href.length - 1) return void 0;
+	const raw = href.slice(hash + 1);
+	let fragment;
+	try {
+		fragment = decodeURIComponent(raw);
+	} catch {
+		return;
+	}
+	return {
+		href,
+		route: href.slice(0, hash),
+		fragment
+	};
+}
+/** Every internal anchor link in a tree, in document order. */
+function collectAnchorLinks(tree) {
+	const links = [];
+	visit(tree, "element", (node) => {
+		if (node.tagName !== "a") return;
+		const href = node.properties.href;
+		if (typeof href !== "string") return;
+		const anchor = splitAnchor(href);
+		if (anchor !== void 0) links.push(anchor);
+	});
+	return links;
+}
+/**
+* Cross-page anchors, once every page has been rendered.
+*
+* `report` is passed in rather than imported so this module stays free of the
+* error factory and the severity plumbing — it answers "which anchors are
+* wrong", and the caller owns what that costs.
+*
+* A link to a route nothing rendered is a *broken link*, not a broken anchor,
+* and `assertLinks` has already reported it at its own severity. Skipped here
+* so one mistake is not two failures.
+*/
+function assertAnchors(docs, report) {
+	const idsByRoute = /* @__PURE__ */ new Map();
+	for (const doc of docs) idsByRoute.set(doc.href, collectAnchorIds(doc.hast));
+	for (const doc of docs) for (const link of collectAnchorLinks(doc.hast)) {
+		if (link.route === "") continue;
+		const known = idsByRoute.get(link.route);
+		if (known === void 0 || known.has(link.fragment)) continue;
+		report(doc.href, link, known);
+	}
+}
+//#endregion
+export { assertAnchors, collectAnchorIds, collectAnchorLinks, splitAnchor };

package/dist/errors.d.ts

@@ -47,6 +47,8 @@ type DocsErrorCode =
 'draft-link' |
 /** A link resolves to an alias, which is a redirect and not a page. */
 'alias-link' |
+/** A `#fragment` that no heading on the target page owns. */
+'broken-anchor' |
 /** An `aliases` entry is empty, escapes the root, or is not URL-safe. */
 'invalid-alias' |
 /** Two pages claim one alias, or an alias shadows a real route. */

package/dist/link-suggestion.d.ts

@@ -0,0 +1,31 @@
+//#region src/link-suggestion.d.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 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.
+ */
+declare function suggestRoute(target: string, routes: Iterable<string>): string | undefined;
+/** ` Did you mean '/installation'?`, or `''` when nothing is close. */
+declare function describeSuggestion(target: string, routes: Iterable<string> | undefined): string;
+//#endregion
+export { describeSuggestion, suggestRoute };

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/next.js

@@ -1,11 +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";
@@ -374,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`;
 	/**

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.
  *
@@ -121,4 +153,4 @@ declare function resolveMarkdownLink(href: string, fromDir: readonly string[], b
  */
 declare const remarkDocLinks: Plugin<[RemarkDocLinksOptions], Root>;
 //#endregion
-export { type DocLinkContext, DocLinkRef, HrefParts, RemarkDocLinksOptions, decodePath, foldSegments, remarkDocLinks, resolveMarkdownLink, splitHref };
+export { type DocLinkContext, DocLinkRef, HrefParts, RemarkDocLinksOptions, decodePath, foldSegments, isRootMount, remarkDocLinks, resolveMarkdownLink, splitHref };

package/dist/plugins/remark-doc-links.js

@@ -20,6 +20,10 @@ const FILE_EXTENSION = /\.[^./]+$/;
 function isRelativeLink(href) {
 	return href !== "" && !href.startsWith("#") && !href.startsWith("?") && !href.startsWith("/") && !HAS_SCHEME.test(href);
 }
+/** No prefix at all — the docs own the whole origin. */
+function isRootMount(basePath) {
+	return basePath.replace(/\/+$/, "") === "";
+}
 /**
 * Is this already-absolute href one of OUR routes?
 *
@@ -28,9 +32,11 @@ function isRelativeLink(href) {
 * A typo in a hand-written absolute link is exactly as likely as one in a
 * relative link; only the rewriting differs.
 *
-* Requires a non-empty base path. Docs mounted at the site root cannot be told
-* apart from the rest of the site, and asserting `/login` against the set of
-* documentation routes would fail builds over links that are perfectly good.
+* Answers `false` at a root mount, where there is no prefix to test against.
+* That is not the end of the matter: the caller records those links anyway,
+* marked, because at a root mount the *common* case is an origin that serves
+* documentation and nothing else — so they are checked, and a site with other
+* routes names them through `externalRoutes`.
 */
 function isInternalAbsoluteLink(href, basePath) {
 	const base = basePath.replace(/\/+$/, "");
@@ -224,23 +230,33 @@ const remarkDocLinks = (options) => {
 			const raw = node.url;
 			if (node.type === "definition" && imageIdentifiers.has(node.identifier)) continue;
 			const line = node.position?.start.line;
-			const record = (href, asset) => {
+			const record = (href, flags = {}) => {
 				const ref = {
 					raw,
 					href
 				};
 				if (line !== void 0) ref.line = line;
-				if (asset !== void 0) ref.asset = asset;
+				if (flags.asset !== void 0) ref.asset = flags.asset;
+				if (flags.unverifiable !== void 0) ref.unverifiable = flags.unverifiable;
+				if (flags.anchorOnly !== void 0) ref.anchorOnly = flags.anchorOnly;
 				refs.push(ref);
 				if (href !== void 0) node.url = href;
 			};
 			try {
+				if (raw.startsWith("#")) {
+					record(raw, { anchorOnly: true });
+					continue;
+				}
 				if (!isRelativeLink(raw)) {
-					if (isInternalAbsoluteLink(raw, basePath) && !isAssetLink(raw)) record(normalizeInternalRoute(raw, basePath));
+					if (isInternalAbsoluteLink(raw, basePath) && !isAssetLink(raw)) {
+						record(normalizeInternalRoute(raw, basePath));
+						continue;
+					}
+					if (isRootMount(basePath) && raw.startsWith("/") && !raw.startsWith("//") && !isAssetLink(raw)) record(normalizeInternalRoute(raw, basePath), { unverifiable: true });
 					continue;
 				}
 				if (resolve === void 0 && isAssetLink(raw)) {
-					record(resolveAssetLink(raw, context.dirSegments, basePath), true);
+					record(resolveAssetLink(raw, context.dirSegments, basePath), { asset: true });
 					continue;
 				}
 				if (resolve) {
@@ -257,4 +273,4 @@ const remarkDocLinks = (options) => {
 	};
 };
 //#endregion
-export { decodePath, foldSegments, remarkDocLinks, resolveMarkdownLink, splitHref };
+export { decodePath, foldSegments, isRootMount, remarkDocLinks, resolveMarkdownLink, splitHref };

package/dist/react/link-adapter.d.ts

@@ -0,0 +1,34 @@
+import { DocsLinkComponent } from "./markdown-components.js";
+import { ComponentProps, ComponentType } from "react";
+//#region src/react/link-adapter.d.ts
+/**
+ * The part of `next/link` this package uses.
+ *
+ * Declared structurally rather than imported: `next` is an optional peer, and
+ * a type-only import of it would still be a hard resolution requirement for
+ * anyone type-checking against our `.d.ts`.
+ */
+type NextLinkComponent = ComponentType<Omit<ComponentProps<'a'>, 'href' | 'ref'> & {
+  href: string;
+  prefetch?: boolean | null;
+}>;
+/**
+ * Adapt `next/link` to {@link DocsLinkProps}.
+ *
+ * `next/link` widens `href` to `string | UrlObject` and `prefetch` to
+ * `boolean | 'auto' | null`; the React layer promises neither, because it must
+ * also run with a plain `<a>`. One wrapper keeps that mismatch in a single
+ * place instead of at every call site.
+ *
+ * `prefetch` is omitted rather than passed as `undefined`, which is not
+ * pedantry: under `exactOptionalPropertyTypes` — which this package compiles
+ * with, and which any consumer may turn on — `undefined` is not assignable to
+ * `boolean | 'auto' | null`, and `<SearchDialog Link={Link} />` written by
+ * hand fails to compile for a reason that reads as our bug.
+ *
+ * Call it once at module scope, never during a render: a fresh component
+ * identity for `a` remounts every link in the document on every render.
+ */
+declare function wrapNextLink(NextLink: NextLinkComponent): DocsLinkComponent;
+//#endregion
+export { NextLinkComponent, wrapNextLink };

package/dist/react/link-adapter.js

@@ -0,0 +1,30 @@
+import { createElement } from "react";
+//#region src/react/link-adapter.ts
+/**
+* Adapt `next/link` to {@link DocsLinkProps}.
+*
+* `next/link` widens `href` to `string | UrlObject` and `prefetch` to
+* `boolean | 'auto' | null`; the React layer promises neither, because it must
+* also run with a plain `<a>`. One wrapper keeps that mismatch in a single
+* place instead of at every call site.
+*
+* `prefetch` is omitted rather than passed as `undefined`, which is not
+* pedantry: under `exactOptionalPropertyTypes` — which this package compiles
+* with, and which any consumer may turn on — `undefined` is not assignable to
+* `boolean | 'auto' | null`, and `<SearchDialog Link={Link} />` written by
+* hand fails to compile for a reason that reads as our bug.
+*
+* Call it once at module scope, never during a render: a fresh component
+* identity for `a` remounts every link in the document on every render.
+*/
+function wrapNextLink(NextLink) {
+	return function DocsNextLink({ href, prefetch, children, ...rest }) {
+		return createElement(NextLink, {
+			...rest,
+			href,
+			...prefetch === void 0 ? {} : { prefetch }
+		}, children);
+	};
+}
+//#endregion
+export { wrapNextLink };

package/dist/react/next-link.d.ts

@@ -1,34 +1,12 @@
 import { DocsLinkComponent } from "./markdown-components.js";
-import { ComponentProps, ComponentType } from "react";
 //#region src/react/next-link.d.ts
 /**
- * The part of `next/link` this package uses.
+ * Module scope, and never inside a render.
  *
- * Declared structurally rather than imported: `next` is an optional peer, and
- * a type-only import of it would still be a hard resolution requirement for
- * anyone type-checking against our `.d.ts`.
+ * A fresh component identity for a link remounts every link in the document on
+ * every render — which is why `next-search.tsx` and `next-nav.tsx` each build
+ * theirs at module scope too, and why this is a constant rather than a factory.
  */
-type NextLinkComponent = ComponentType<Omit<ComponentProps<'a'>, 'href' | 'ref'> & {
-  href: string;
-  prefetch?: boolean | null;
-}>;
-/**
- * Adapt `next/link` to {@link DocsLinkProps}.
- *
- * `next/link` widens `href` to `string | UrlObject` and `prefetch` to
- * `boolean | 'auto' | null`; the React layer promises neither, because it must
- * also run with a plain `<a>`. One wrapper keeps that mismatch in a single
- * place instead of at every call site.
- *
- * `prefetch` is omitted rather than passed as `undefined`, which is not
- * pedantry: under `exactOptionalPropertyTypes` — which this package compiles
- * with, and which any consumer may turn on — `undefined` is not assignable to
- * `boolean | 'auto' | null`, and `<SearchDialog Link={Link} />` written by
- * hand fails to compile for a reason that reads as our bug.
- *
- * Call it once at module scope, never during a render: a fresh component
- * identity for `a` remounts every link in the document on every render.
- */
-declare function wrapNextLink(NextLink: NextLinkComponent): DocsLinkComponent;
+declare const DocsLink: DocsLinkComponent;
 //#endregion
-export { NextLinkComponent, wrapNextLink };
+export { DocsLink };

package/dist/react/next-link.js

@@ -1,30 +1,51 @@
-import { createElement } from "react";
-//#region src/react/next-link.ts
+"use client";
+import { wrapNextLink } from "./link-adapter.js";
+import NextLink from "next/link";
+//#region src/react/next-link.tsx
 /**
-* Adapt `next/link` to {@link DocsLinkProps}.
+* `next/link`, adapted to this package's {@link DocsLinkProps} and ready to pass.
 *
-* `next/link` widens `href` to `string | UrlObject` and `prefetch` to
-* `boolean | 'auto' | null`; the React layer promises neither, because it must
-* also run with a plain `<a>`. One wrapper keeps that mismatch in a single
-* place instead of at every call site.
+* ⚠️ IT EXISTS BECAUSE PASSING `next/link` DIRECTLY DOES NOT TYPE-CHECK. Under
+* `exactOptionalPropertyTypes` — which this package compiles with, and which any
+* consumer may turn on — Next's `LinkProps` re-declares `onClick?`,
+* `onMouseEnter?` and `onTouchStart?` *without* `| undefined` while React's
+* anchor props include it, so `<DocsSidebar Link={Link} />` fails to compile
+* over three handlers `next/link` accepts perfectly well at run time. It is a
+* disagreement between two dependencies' declaration files, true of every
+* `next/link` call site in a project with that flag on, and nothing the shape of
+* `DocsLinkProps` can fix without breaking the plain-`<a>` fallback that makes
+* these components host-agnostic.
 *
-* `prefetch` is omitted rather than passed as `undefined`, which is not
-* pedantry: under `exactOptionalPropertyTypes` — which this package compiles
-* with, and which any consumer may turn on — `undefined` is not assignable to
-* `boolean | 'auto' | null`, and `<SearchDialog Link={Link} />` written by
-* hand fails to compile for a reason that reads as our bug.
+* `docs.Layout` and `DocsSearch` have always absorbed it internally, so it only
+* ever bit someone composing a shell by hand — who was told to write
+* `Link={Link as DocsLinkComponent}` and wait for this module. This is it; the
+* cast is retired.
 *
-* Call it once at module scope, never during a render: a fresh component
-* identity for `a` remounts every link in the document on every render.
+* ```tsx
+* 'use client';
+* import { DocsLink } from '@waveso/docs/react/next-link';
+* import { DocsSidebar } from '@waveso/docs/react/sidebar';
+*
+* <DocsSidebar nav={nav} pathname={pathname} Link={DocsLink} />
+* ```
+*
+* ## Why `'use client'`
+*
+* Not for a hook — there is none. {@link DocsLink} is a *function*, and a
+* function cannot be handed from a Server Component to a Client one: React
+* serialises those props and refuses. Without the directive this module's export
+* would be a server reference, and passing it to `DocsSidebar` — which is itself
+* `'use client'` — would fail `next build` with "Functions cannot be passed
+* directly to Client Components". The directive makes it a client reference,
+* which crosses fine.
+*/
+/**
+* Module scope, and never inside a render.
+*
+* A fresh component identity for a link remounts every link in the document on
+* every render — which is why `next-search.tsx` and `next-nav.tsx` each build
+* theirs at module scope too, and why this is a constant rather than a factory.
 */
-function wrapNextLink(NextLink) {
-	return function DocsNextLink({ href, prefetch, children, ...rest }) {
-		return createElement(NextLink, {
-			...rest,
-			href,
-			...prefetch === void 0 ? {} : { prefetch }
-		}, children);
-	};
-}
+const DocsLink = wrapNextLink(NextLink);
 //#endregion
-export { wrapNextLink };
+export { DocsLink };

package/dist/react/next-nav.js

@@ -1,5 +1,5 @@
 "use client";
-import { wrapNextLink } from "./next-link.js";
+import { wrapNextLink } from "./link-adapter.js";
 import { DocsNav } from "./nav.js";
 import { jsx } from "react/jsx-runtime";
 import NextLink from "next/link";

package/dist/react/next-search.js

@@ -1,5 +1,5 @@
 "use client";
-import { wrapNextLink } from "./next-link.js";
+import { wrapNextLink } from "./link-adapter.js";
 import { SearchDialog } from "./search-dialog.js";
 import { useCallback } from "react";
 import { jsx } from "react/jsx-runtime";

package/dist/render.d.ts

@@ -12,7 +12,7 @@ import { PluggableList } from "unified";
  * same object to the source walk and to the renderer. Nothing here re-applies
  * defaults, so the two cannot drift.
  */
-type DocsRendererConfig = Pick<ResolvedDocsConfig, 'basePath' | 'assertLinks'>;
+type DocsRendererConfig = Pick<ResolvedDocsConfig, 'basePath' | 'onBrokenLinks' | 'onBrokenAnchors' | 'externalRoutes'>;
 interface DocsRendererOptions {
   config: DocsRendererConfig;
   /**

package/dist/render.js

@@ -1,5 +1,7 @@
+import { collectAnchorIds, splitAnchor } from "./anchors.js";
 import { docsError } from "./docs-error.js";
 import { DEFAULT_DOCS_THEMES, createDocsHighlighter } from "./highlighter.js";
+import { describeSuggestion } from "./link-suggestion.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";
@@ -8,6 +10,7 @@ import { rehypeFlattenRoots } from "./plugins/rehype-flatten-roots.js";
 import { foldSegments, remarkDocLinks, resolveMarkdownLink, splitHref } from "./plugins/remark-doc-links.js";
 import { remarkUnwrapImages } from "./plugins/remark-unwrap-images.js";
 import { remarkYouTube } from "./plugins/remark-youtube.js";
+import { visit } from "unist-util-visit";
 import rehypeShikiFromHighlighter from "@shikijs/rehype/core";
 import { rehypeGithubAlerts } from "rehype-github-alerts";
 import rehypeAutolinkHeadings from "rehype-autolink-headings";
@@ -16,7 +19,6 @@ import remarkGfm from "remark-gfm";
 import remarkParse from "remark-parse";
 import remarkRehype from "remark-rehype";
 import { unified } from "unified";
-import { visit } from "unist-util-visit";
 import { VFile } from "vfile";
 //#region src/render.ts
 /**
@@ -121,6 +123,18 @@ function withSuffix(src, suffix) {
 	return `${src}${suffix}`;
 }
 /** Route without its `?query` / `#anchor`, for existence checks. */
+/**
+* Does this route belong to the host application rather than the docs?
+*
+* Prefix match on a segment boundary, so `/api` covers `/api/keys` and does not
+* accidentally cover `/apiary`.
+*/
+function isExternalRoute(route, external) {
+	return external.some((prefix) => {
+		const trimmed = prefix.replace(/\/+$/, "");
+		return route === trimmed || route.startsWith(`${trimmed}/`);
+	});
+}
 function toRouteKey(href) {
 	const cut = href.search(/[?#]/);
 	return cut === -1 ? href : href.slice(0, cut);
@@ -343,21 +357,65 @@ function createDocsRenderer(options) {
 		}));
 	}
 	/**
-	* Fail the build on a link that would have 404'd.
+	* Act on a link problem at the severity the site chose.
+	*
+	* ⚠️ `'throw'` IS THE DEFAULT AND SHOULD STAY IT. The link was valid in the
+	* editor and on GitHub, so a warning in a build log is a warning nobody
+	* reads. The setting exists because a migration may knowingly run against an
+	* incomplete corpus for a while and the tool cannot know that — which is the
+	* same reason Docusaurus has one.
+	*/
+	function report(severity, code, message) {
+		if (severity === "ignore") return;
+		if (severity === "throw") throw docsError(code, message);
+		console.warn(docsError(code, message).message);
+	}
+	/**
+	* Anchors that point into the page being rendered.
+	*
+	* ⚠️ HERE, NOT IN THE CORPUS PASS, BECAUSE THIS IS WHERE THE LINE NUMBER IS.
+	* The recorded refs carry the source line and the tree still has its
+	* positions; both are gone from a returned `RenderedDoc`. A same-page anchor
+	* is also the one a writer produces most — every "see below" — so it is worth
+	* the better message.
 	*
-	* Deliberately a throw and not a warning: the link was valid in the editor
-	* and on GitHub, so a warning in a build log is a warning nobody reads.
+	* Cross-page anchors need the other page's ids and are checked by
+	* `renderAll`, which is the first point at which they exist.
 	*/
+	function assertOwnAnchors(file, tree, refs) {
+		if (config.onBrokenAnchors === "ignore") return;
+		let ids;
+		for (const ref of refs) {
+			const anchor = splitAnchor(ref.href ?? ref.raw);
+			if (anchor === void 0) continue;
+			if (anchor.route !== "" && anchor.route !== file.href) continue;
+			ids ??= collectAnchorIds(tree);
+			if (ids.has(anchor.fragment)) continue;
+			report(config.onBrokenAnchors, "broken-anchor", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', and this page has no '#${anchor.fragment}'.${describeSuggestion(anchor.fragment, ids)} Heading ids come from the heading text, so renaming a heading renames its anchor.`);
+		}
+	}
+	/** Check every link a page recorded, and act at the configured severity. */
 	function assertLinks(file, refs) {
 		for (const ref of refs) {
-			if (ref.href === void 0) throw docsError("broken-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which does not resolve to a documentation page. Use a path relative to this file, or an absolute URL for external links.`);
-			if (knownRoutes === void 0 || ref.asset) continue;
+			if (ref.anchorOnly) continue;
+			if (ref.href === void 0) {
+				report(config.onBrokenLinks, "broken-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which does not resolve to a documentation page. Use a path relative to this file, or an absolute URL for external links.`);
+				continue;
+			}
+			if (knownRoutes === void 0 || ref.asset || ref.anchorOnly) continue;
 			const route = toRouteKey(ref.href);
+			if (isExternalRoute(route, config.externalRoutes)) continue;
 			if (knownRoutes.has(route)) continue;
-			if (draftRoutes?.has(route)) throw docsError("draft-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which resolves to '${route}' — a page marked \`draft: true\`, so it is not published and the link would 404. Publish the page, remove the link, or build with \`includeDrafts\`.`);
+			if (draftRoutes?.has(route)) {
+				report(config.onBrokenLinks, "draft-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which resolves to '${route}' — a page marked \`draft: true\`, so it is not published and the link would 404. Publish the page, remove the link, or build with \`includeDrafts\`.`);
+				continue;
+			}
 			const aliasTarget = aliasRoutes?.get(route);
-			if (aliasTarget !== void 0) throw docsError("alias-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which resolves to '${route}' — an alias that redirects to '${aliasTarget}'. An alias is not a page: it 404s unless \`createDocsRedirects\` is wired into \`next.config.ts\`, and it is never prerendered. Link to '${aliasTarget}' directly.`);
-			throw docsError("broken-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which resolves to '${route}' — no such page exists. Fix the link, or add an \`aliases\` entry to the page it used to point at.`);
+			if (aliasTarget !== void 0) {
+				report(config.onBrokenLinks, "alias-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which resolves to '${route}' — an alias that redirects to '${aliasTarget}'. An alias is not a page: it 404s unless \`createDocsRedirects\` is wired into \`next.config.ts\`, and it is never prerendered. Link to '${aliasTarget}' directly.`);
+				continue;
+			}
+			report(config.onBrokenLinks, "broken-link", `@waveso/docs: ${describeLink(file, ref)} links to '${ref.raw}', which resolves to '${route}' — no such page exists.${describeSuggestion(route, knownRoutes)} Fix the link, or add an \`aliases\` entry to the page it used to point at.`);
 		}
 	}
 	return { async render(file) {
@@ -375,7 +433,8 @@ function createDocsRenderer(options) {
 		const hast = await processor.run(processor.parse(vfile), vfile);
 		if (titleHeading && !hasHeadingOne(hast)) hast.children.unshift(titleHeadingNode(file.frontmatter.title));
 		await resolveImages(hast, file, imageResolver);
-		if (config.assertLinks) assertLinks(file, vfile.data.docLinks ?? []);
+		assertLinks(file, vfile.data.docLinks ?? []);
+		assertOwnAnchors(file, hast, vfile.data.docLinks ?? []);
 		return {
 			frontmatter: file.frontmatter,
 			hast: stripPositions(hast),

package/dist/source.js

@@ -71,7 +71,9 @@ function resolveDocsConfig(config) {
 		),
 		basePath: normalizeBasePath(config.basePath ?? "/docs"),
 		includeDrafts: config.includeDrafts ?? false,
-		assertLinks: config.assertLinks ?? true,
+		onBrokenLinks: config.onBrokenLinks ?? "throw",
+		onBrokenAnchors: config.onBrokenAnchors ?? "throw",
+		externalRoutes: config.externalRoutes ?? [],
 		...config.frontmatterSchema === void 0 ? {} : { frontmatterSchema: config.frontmatterSchema }
 	};
 }
@@ -114,7 +116,9 @@ function createDocsSource(config) {
 		resolved.contentDir,
 		resolved.basePath,
 		resolved.includeDrafts,
-		resolved.assertLinks,
+		resolved.onBrokenLinks,
+		resolved.onBrokenAnchors,
+		resolved.externalRoutes.join(","),
 		schemaKey(resolved.frontmatterSchema)
 	].join("\0");
 	const existing = sources.get(key);

package/dist/types.d.ts

@@ -244,11 +244,24 @@ interface DocLinkContext {
   /** The source path, e.g. `'api/auth.md'`. For error messages. */
   relativePath: string;
 }
+/**
+ * What a link problem should do to a build.
+ *
+ * The three Docusaurus settled on, and for the same reason: the tool cannot
+ * know how much a given site cares, and guessing produces either a build that
+ * fails on someone's legitimate URL or one that ships a dead link quietly.
+ *
+ * `'warn'` writes to `console.warn` and continues, which on a docs site is a
+ * line in a build log — useful during a migration, not a substitute for
+ * `'throw'`.
+ */
+type DocsLinkSeverity = 'throw' | 'warn' | 'ignore';
 /**
  * Resolve an internal markdown link target to a route.
  *
  * Called for every relative link found in the source. Returning `undefined`
- * signals "not a documentation page", which — with `assertLinks` on — fails
+ * signals "not a documentation page", which — under the default
+ * `onBrokenLinks: 'throw'` — fails
  * the build rather than shipping a 404 that was valid on GitHub.
  */
 type LinkResolver = (
@@ -321,10 +334,61 @@ interface DocsConfig<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
    */
   includeDrafts?: boolean | undefined;
   /**
-   * Fail the build when an internal link resolves to a page that does not
-   * exist. Defaults to `true`; there is no good reason to turn it off.
+   * What to do about an internal link that resolves to no published page.
+   * Defaults to `'throw'`.
+   *
+   * A link that 404s was valid in the editor and on GitHub, so it is the kind
+   * of mistake nobody finds by reading. Throwing is the default for that
+   * reason, and there is rarely a good reason to lower it — `'warn'` exists
+   * for a migration where the corpus is knowingly incomplete for a while.
+   *
+   * The error names the file and the line, and offers the closest published
+   * route when the link looks like a typo of one.
+   */
+  onBrokenLinks?: DocsLinkSeverity | undefined;
+  /**
+   * What to do about a `#fragment` that no heading on the target page owns.
+   * Defaults to `'throw'`.
+   *
+   * ⚠️ THE MORE COMMON OF THE TWO LINK FAILURES, AND IT WENT UNCHECKED. A route
+   * was verified and its fragment discarded, so `[setup](./install.md#setup)`
+   * built green with no `#setup` anywhere on the page. Headings get renamed
+   * constantly and nothing renames the links into them, which is exactly why it
+   * is worth checking and exactly why it breaks.
+   *
+   * Checked against every `id` in the rendered page rather than against the
+   * table of contents, which captures `h2`–`h3` only — so a link to an `h4` is
+   * fine, and so is one to an id a `rehypePlugins` entry put on something that
+   * is not a heading.
+   *
+   * Lower it to `'warn'` if a plugin of yours adds ids this package cannot see
+   * at render time.
+   */
+  onBrokenAnchors?: DocsLinkSeverity | undefined;
+  /**
+   * Route prefixes that belong to your application, not to the documentation.
+   *
+   * ⚠️ ONLY MEANINGFUL AT A ROOT MOUNT, WHICH IS ALSO THE ONLY PLACE IT IS
+   * NEEDED. Under `basePath: '/docs'` an absolute link either carries the
+   * prefix — so it is documentation and is checked — or it does not, and this
+   * package leaves it alone. Under `basePath: '/'` there is no prefix to test
+   * against: `/setup` and `/login` look identical, and both are checked against
+   * the published pages.
+   *
+   * That is the right default, because a root mount is what you choose when the
+   * origin serves documentation and nothing else — `docs.example.com` — and
+   * there an unknown absolute link is always a typo. If the origin *does* serve
+   * something else, name what is yours:
+   *
+   * ```ts
+   * externalRoutes: ['/login', '/dashboard', '/api/']
+   * ```
+   *
+   * A link is skipped when it equals one of these or begins with one followed
+   * by `/`. It is a statement about your application, so nothing here can infer
+   * it and nothing tries.
    */
-  assertLinks?: boolean | undefined;
+  externalRoutes?: readonly string[] | undefined;
   /**
    * Validates every page's frontmatter. Defaults to `docFrontmatterSchema`
    * from `@waveso/docs/frontmatter`.
@@ -375,7 +439,9 @@ interface ResolvedDocsConfig<TFrontmatter extends DocFrontmatter = DocFrontmatte
   contentDir: string;
   basePath: string;
   includeDrafts: boolean;
-  assertLinks: boolean;
+  onBrokenLinks: DocsLinkSeverity;
+  onBrokenAnchors: DocsLinkSeverity;
+  externalRoutes: readonly string[];
   /**
    * As supplied. `resolveDocsConfig` omits the key rather than setting it to
    * `undefined` when the built-in `docFrontmatterSchema` applies, so the
@@ -384,4 +450,4 @@ interface ResolvedDocsConfig<TFrontmatter extends DocFrontmatter = DocFrontmatte
   frontmatterSchema?: StandardSchemaV1<unknown, TFrontmatter> | undefined;
 }
 //#endregion
-export { DocFile, DocFrontmatter, DocLinkContext, DocNavGroup, DocNavLink, DocNavNode, DocNavPage, DocNavSeparator, DocsConfig, DocsMeta, ImageResolver, LinkResolver, RenderedDoc, ResolvedDocsConfig, SearchRecord, TocEntry };
+export { DocFile, DocFrontmatter, DocLinkContext, DocNavGroup, DocNavLink, DocNavNode, DocNavPage, DocNavSeparator, DocsConfig, DocsLinkSeverity, DocsMeta, ImageResolver, LinkResolver, RenderedDoc, ResolvedDocsConfig, SearchRecord, TocEntry };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@waveso/docs",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Zero parser bytes in the browser: markdown docs for Next.js, built to hast in Node and rendered as your components",
   "type": "module",
   "sideEffects": [
@@ -76,6 +76,10 @@
       "types": "./dist/react/markdown-components.d.ts",
       "default": "./dist/react/markdown-components.js"
     },
+    "./react/next-link": {
+      "types": "./dist/react/next-link.d.ts",
+      "default": "./dist/react/next-link.js"
+    },
     "./react/next-search": {
       "types": "./dist/react/next-search.d.ts",
       "default": "./dist/react/next-search.js"
@@ -196,7 +200,6 @@
     "test:smoke": "node smoke/check.ts",
     "size": "node scripts/size.ts",
     "build:site": "next build site",
-    "dev:site": "next dev site",
-    "shoot": "node scripts/shoot.ts"
+    "dev:site": "next dev site"
   }
 }