@waveso/docs 0.5.0 → 0.7.0

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) {
@@ -373,9 +431,11 @@ function createDocsRenderer(options) {
 			relativePath: file.relativePath
 		};
 		const hast = await processor.run(processor.parse(vfile), vfile);
-		if (titleHeading && !hasHeadingOne(hast)) hast.children.unshift(titleHeadingNode(file.frontmatter.title));
+		const hasHero = (file.frontmatter.actions?.length ?? 0) > 0;
+		if (titleHeading && !hasHero && !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

@@ -18,7 +18,7 @@ const INDEX_NAME = "index";
 * ⚠️ THE SCAN USED TO OPEN EVERY MARKDOWN FILE AT ONCE. `scanDir` recursed into
 * its subdirectories in parallel and read that directory's pages with a bare
 * `Promise.all`, so the number of `readFile` calls in flight equalled the number
-* of markdown files in the entire tree. On a 1,200-page corpus and the common
+* of markdown files in the entire tree. On a 1,201-page corpus and the common
 * 1,024-descriptor soft limit, `next build` died with a bare `EMFILE: too many
 * open files` — no error code, no mention that this was the docs scan, and
 * nothing pointing at the fix. Exactly the large content set this package is
@@ -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);