@waveso/docs 0.1.0

package/dist/next.d.ts

@@ -0,0 +1,256 @@
+import { DocFile, DocFrontmatter, DocsConfig, ImageResolver, LinkResolver, RenderedDoc } from "./types.js";
+import { DocsHighlighter, DocsLang, DocsTheme, DocsThemes } from "./highlighter.js";
+import { MarkdownComponents } from "./react/markdown-components.js";
+import { DocsSource } from "./source.js";
+import { ReactNode } from "react";
+//#region src/next.d.ts
+interface DocsRouteOptions<TFrontmatter extends DocFrontmatter = DocFrontmatter> extends DocsConfig<TFrontmatter> {
+  /** Overrides merged over the Next-flavoured defaults (`next/link` + `next/image`). */
+  components?: MarkdownComponents;
+  /** Reuse an existing Shiki highlighter. */
+  highlighter?: DocsHighlighter | Promise<DocsHighlighter>;
+  /** Grammars to load, when building the default highlighter. */
+  langs?: readonly DocsLang[];
+  /** Theme pair. */
+  themes?: DocsThemes;
+  /**
+   * Prepend an `<h1>` from `frontmatter.title` when the markdown has none.
+   * Defaults to `true`; turn it off if your layout renders the title itself.
+   */
+  titleHeading?: boolean;
+  /**
+   * `id` of the rendered `<article>`, which is also what
+   * `@waveso/docs/react/skip-link` targets by default. Defaults to
+   * `'docs-content'`. Pass `false` to render no id at all.
+   */
+  contentId?: string | false;
+  /**
+   * Re-read the content directory on every request.
+   *
+   * Defaults to `true` outside `NODE_ENV=production`. Markdown files are not in
+   * Next's module graph, so nothing re-evaluates a route module when one
+   * changes: without this, `next dev` serves whatever it read on the first
+   * request until the server restarts, and a file added afterwards is never
+   * found. A rescan of a few hundred small files costs single-digit
+   * milliseconds; a production build reads the tree once, as it should.
+   */
+  rescanPerRequest?: boolean;
+  /** Replaces the built-in markdown-link resolution. */
+  linkResolver?: LinkResolver;
+  /**
+   * Resolves image `src` to a public URL and intrinsic dimensions. Without one,
+   * markdown images render as a plain `<img>`: `next/image` refuses to render
+   * without dimensions, and markdown carries none.
+   */
+  imageResolver?: ImageResolver;
+  /**
+   * Absolute site origin, e.g. `'https://example.com'`.
+   *
+   * When set, `alternates.canonical` is an absolute URL. When omitted it is a
+   * root-relative path, which Next resolves against `metadataBase` — so if you
+   * set neither, you ship pages with no usable canonical.
+   */
+  siteUrl?: string;
+}
+/** Props Next hands a page in the App Router. */
+interface DocsPageProps {
+  /**
+   * Next 16 passes route params as a promise, and reading it without awaiting
+   * yields a `Promise` object where a string array was expected.
+   *
+   * `slug` is optional so one signature serves both the catch-all route and
+   * the index route, which has no params at all.
+   */
+  params: Promise<{
+    slug?: string[];
+  }>;
+}
+/**
+ * Page metadata, shaped to be assignable to Next's `Metadata`.
+ *
+ * Structural rather than imported for the same reason as
+ * {@link NextLinkComponent}: `next` is optional, and our published types must
+ * not require it.
+ */
+interface DocsPageMetadata {
+  title?: string;
+  description?: string;
+  alternates?: {
+    canonical: string;
+  };
+  openGraph?: {
+    type: 'article';
+    title: string;
+    description?: string;
+    url: string;
+  };
+}
+/**
+ * What {@link createDocsRoute} returns.
+ *
+ * The type parameter comes from `frontmatterSchema` on the options, so
+ * `docs.getPage(...)` and `docs.source.all()` hand back your own frontmatter
+ * fields without a type argument anywhere in the route file.
+ */
+interface DocsRoute<TFrontmatter extends DocFrontmatter = DocFrontmatter> {
+  /**
+   * Default export for `app/<basePath>/[...slug]/page.tsx`.
+   *
+   * The catch-all is required — see {@link DocsRoute.IndexPage}.
+   */
+  Page: (props: DocsPageProps) => Promise<ReactNode>;
+  /**
+   * Default export for `app/<basePath>/page.tsx`. Renders the content root's
+   * `index.md`.
+   *
+   * This second file is not optional, and leaving it out is the most common way
+   * to ship this broken. `[...slug]` does not match `/docs` itself: the route
+   * table emits `/docs/index`, and `/docs` returns 404.
+   *
+   * The fix is a sibling `page.tsx`, *not* an optional catch-all `[[...slug]]`.
+   * The optional form does match `/docs`, but it also leaves `/docs/index` live
+   * and serving byte-identical HTML — a duplicate-content pair with no
+   * canonical between them — and it makes `params.slug` possibly `undefined`
+   * for every page.
+   */
+  IndexPage: () => Promise<ReactNode>;
+  /**
+   * `generateStaticParams` for the catch-all route.
+   *
+   * The root `index.md` is deliberately absent: its segments are `[]`, and a
+   * catch-all cannot render an empty parameter list. It is served by
+   * {@link DocsRoute.IndexPage}.
+   */
+  generateStaticParams: () => Promise<Array<{
+    slug: string[];
+  }>>;
+  /** `generateMetadata` for either route file. Sets `alternates.canonical`. */
+  generateMetadata: (props: DocsPageProps) => Promise<DocsPageMetadata>;
+  /**
+   * The value your route file must declare. Read it, do not re-export it.
+   *
+   * ```ts
+   * export const dynamicParams = false; // ✅ a literal
+   * export const dynamicParams = docs.dynamicParams; // ❌ fails the build
+   * ```
+   *
+   * Route segment config is statically parsed out of the module by the
+   * compiler, before any of it runs, so it has to be a literal. A member
+   * expression fails `next build` outright with "Next.js can't recognize the
+   * exported `dynamicParams` field in route. It needs to be a static boolean."
+   * (verified against Next 16.3.0 / Turbopack). This field exists so the value
+   * is documented in one place and typed as `false`, not so it can be
+   * forwarded.
+   *
+   * Declaring it is not optional. Next defaults `dynamicParams` to `true`,
+   * which means a URL that `generateStaticParams` never listed is still
+   * rendered on demand — so `/docs/typo` reaches the source layer,
+   * `fs.readFile` throws `ENOENT`, and Next answers **HTTP 500**. Google
+   * treats a 5xx as a crawl failure and retries it; it treats a 404 as an
+   * answer. With the full page set known at build time there is nothing to
+   * render on demand anyway.
+   */
+  dynamicParams: false;
+  /**
+   * The underlying source, for layouts: `docs.source.nav()` feeds
+   * `DocsSidebar`.
+   */
+  source: DocsSource<TFrontmatter>;
+  /**
+   * Render one page yourself, for a custom layout that needs the TOC or the
+   * frontmatter alongside the content. Resolves to `undefined` when no such
+   * page exists, or when it is a draft and `includeDrafts` is off.
+   */
+  getPage: (segments: string[]) => Promise<RenderedDoc<TFrontmatter> | undefined>;
+  /**
+   * Every published page, rendered. The input to
+   * `extractSearchRecords`/`writeSearchIndex` — nothing builds the search index
+   * for you.
+   */
+  renderAll: () => Promise<Array<RenderedDoc<TFrontmatter>>>;
+}
+/**
+ * Create the route handlers for a documentation tree.
+ *
+ * Call it once at module scope in each of the two route files. The filesystem
+ * scan, the highlighter and the component map are all shared per process, so
+ * the second call is free.
+ */
+declare function createDocsRoute<TFrontmatter extends DocFrontmatter = DocFrontmatter>(options: DocsRouteOptions<TFrontmatter>): DocsRoute<TFrontmatter>;
+/** One entry of Next's `MetadataRoute.Sitemap`. */
+interface DocsSitemapEntry {
+  url: string;
+  lastModified?: Date;
+  changeFrequency?: 'always' | 'hourly' | 'daily' | 'weekly' | 'monthly' | 'yearly' | 'never';
+  priority?: number;
+}
+interface DocsSitemapOptions<TFrontmatter extends DocFrontmatter = DocFrontmatter> extends DocsConfig<TFrontmatter> {
+  /**
+   * Absolute site origin, e.g. `'https://example.com'`. Required: sitemap
+   * URLs must be absolute, and a relative one makes the whole file invalid.
+   */
+  siteUrl: string;
+  /** Applied to every entry. Omitted by default — Google ignores it anyway. */
+  changeFrequency?: DocsSitemapEntry['changeFrequency'];
+  /** Applied to every entry. Omitted by default. */
+  priority?: number;
+  /**
+   * Override the last-modified date per page.
+   *
+   * The default is the file's mtime, which on a CI runner is the *checkout*
+   * time — every page then claims to have changed today, and `lastmod` becomes
+   * noise. Wire this to your git history if the dates are load-bearing.
+   */
+  lastModified?: (file: DocFile<TFrontmatter>) => Date | undefined | Promise<Date | undefined>;
+}
+/**
+ * Sitemap entries for every published page, for `app/sitemap.ts`.
+ *
+ * Drafts are excluded, as are aliases — an alias is a redirect, and listing a
+ * redirect in a sitemap is a crawl error.
+ *
+ * ```ts
+ * // app/sitemap.ts
+ * import { createDocsSitemap } from '@waveso/docs/next';
+ *
+ * export default async function sitemap() {
+ *   return createDocsSitemap({
+ *     contentDir: 'content/docs',
+ *     siteUrl: 'https://example.com',
+ *   });
+ * }
+ * ```
+ */
+declare function createDocsSitemap<TFrontmatter extends DocFrontmatter = DocFrontmatter>(options: DocsSitemapOptions<TFrontmatter>): Promise<DocsSitemapEntry[]>;
+/** One entry of `next.config`'s `redirects()`. */
+interface DocsRedirect {
+  source: string;
+  destination: string;
+  /** Always `true`: a renamed page is not coming back to its old URL. */
+  permanent: true;
+}
+/**
+ * Permanent redirects from every page's `aliases` frontmatter.
+ *
+ * Renaming a documentation page otherwise breaks every inbound link that ever
+ * pointed at it — search results, blog posts, Stack Overflow answers, other
+ * people's bookmarks. Adding one line of frontmatter should be the whole cost
+ * of a rename.
+ *
+ * ```ts
+ * // next.config.ts
+ * import { createDocsRedirects } from '@waveso/docs/next';
+ *
+ * export default {
+ *   redirects: () => createDocsRedirects({ contentDir: 'content/docs' }),
+ * };
+ * ```
+ *
+ * Aliases are resolved against the docs base path, so `aliases: ['quickstart']`
+ * on `/docs/getting-started` redirects `/docs/quickstart`. Throws when two
+ * pages claim the same alias, or when an alias collides with a real page —
+ * both silently lose a page otherwise, and both are typos.
+ */
+declare function createDocsRedirects(config: DocsConfig): Promise<DocsRedirect[]>;
+//#endregion
+export { type DocsLang, DocsPageMetadata, DocsPageProps, DocsRedirect, DocsRoute, DocsRouteOptions, DocsSitemapEntry, DocsSitemapOptions, type DocsTheme, type DocsThemes, createDocsRedirects, createDocsRoute, createDocsSitemap };

package/dist/next.js

@@ -0,0 +1,365 @@
+import { createMarkdownComponents } from "./react/markdown-components.js";
+import { DocContent } from "./react/doc-content.js";
+import "./react/skip-link.js";
+import { createDocsRenderer } from "./render.js";
+import { createDocsSource, resolveDocsConfig, toAliasRoute } from "./source.js";
+import { stat } from "node:fs/promises";
+import { createElement } from "react";
+//#region src/next.ts
+/**
+* The Next.js App Router adapter.
+*
+* Wires a content directory to a catch-all route in five lines, with the
+* details that separate a docs site Google indexes from one it does not:
+* `dynamicParams: false`, a real index route, awaited `params`, and a canonical
+* URL on every page.
+*
+* Two route files are required — see {@link DocsRoute.IndexPage} for why:
+*
+* ```tsx
+* // app/docs/[...slug]/page.tsx
+* import { createDocsRoute } from '@waveso/docs/next';
+*
+* const docs = createDocsRoute({ contentDir: 'content/docs' });
+*
+* export default docs.Page;
+* export const generateStaticParams = docs.generateStaticParams;
+* export const generateMetadata = docs.generateMetadata;
+* export const dynamicParams = false; // must be a literal, see `DocsRoute`
+* ```
+*
+* ```tsx
+* // app/docs/page.tsx
+* import { createDocsRoute } from '@waveso/docs/next';
+*
+* const docs = createDocsRoute({ contentDir: 'content/docs' });
+*
+* export default docs.IndexPage;
+* export const generateMetadata = docs.generateMetadata;
+* ```
+*
+* `next` is an *optional* peer dependency, so its modules are imported lazily
+* and only from the code paths that render. That is what lets
+* {@link createDocsSitemap} and {@link createDocsRedirects} be called from
+* `next.config.ts` — which Node loads outside the Next runtime — without
+* dragging React and Next's client runtime into the config load.
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null;
+}
+/**
+* Pull the default export out of a lazily-imported module.
+*
+* This is the one place a cast is unavoidable — the import crosses a boundary
+* the compiler cannot see. It is guarded by a runtime check so a missing or
+* mis-shaped `next` surfaces as an error naming the package to install, rather
+* than as `undefined is not a function` four frames inside React.
+*/
+function readDefaultExport(mod, specifier) {
+	const value = isRecord(mod) && "default" in mod ? mod.default : mod;
+	if (typeof value !== "function" && !isRecord(value)) throw new Error(`@waveso/docs: '${specifier}' has no usable default export. The \`@waveso/docs/next\` entry point requires Next.js 16 — install \`next\`, or build your pages from \`@waveso/docs/react/*\` instead.`);
+	return value;
+}
+/**
+* Import a `next` module, or explain what is missing.
+*
+* Node's own `ERR_MODULE_NOT_FOUND` for `next/navigation` names a file inside
+* this package, which reads as our bug rather than a missing peer — and the
+* most likely way to reach it is importing `@waveso/docs/next` from a non-Next
+* app, where the fix is to use `@waveso/docs/react/*` with your own loader.
+*/
+async function importNext(load, specifier) {
+	try {
+		return await load();
+	} catch (error) {
+		throw new Error(`@waveso/docs: could not load '${specifier}'. The \`@waveso/docs/next\` entry point needs Next.js 16, which is an optional peer dependency — install \`next\`. Outside Next, build your pages from \`@waveso/docs/react/*\` and load content yourself with \`@waveso/docs/source\` and \`@waveso/docs/render\`.`, { cause: error });
+	}
+}
+async function loadNotFound() {
+	const mod = await importNext(() => import("next/navigation"), "next/navigation");
+	const value = isRecord(mod) ? mod.notFound : void 0;
+	if (typeof value !== "function") throw new Error("@waveso/docs: 'next/navigation' has no `notFound` export. The `@waveso/docs/next` entry point requires Next.js 16.");
+	return value;
+}
+/**
+* Adapt `next/link` to {@link DocsLinkProps}.
+*
+* `next/link` widens `href` to `string | UrlObject` and `prefetch` to
+* `boolean | 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.
+*/
+function wrapNextLink(NextLink) {
+	return function DocsNextLink({ href, prefetch, children, ...rest }) {
+		return createElement(NextLink, {
+			...rest,
+			href,
+			...prefetch === void 0 ? {} : { prefetch }
+		}, children);
+	};
+}
+/**
+* Adapt `next/image` to {@link DocsImageProps}.
+*
+* Every prop is named rather than spread. `next/image` types `width`/`height`
+* as `number | \`${number}\``, and spreading a `ComponentProps<'img'>`-shaped
+* object into it fails with TS2322 because the DOM types allow a bare `string`.
+* The build-time {@link ImageResolver} has already produced real numbers here.
+*/
+function wrapNextImage(NextImage) {
+	return function DocsNextImage({ src, alt, width, height, title, className, sizes, loading }) {
+		return createElement(NextImage, {
+			src,
+			alt,
+			width,
+			height,
+			...title === void 0 ? {} : { title },
+			...className === void 0 ? {} : { className },
+			...sizes === void 0 ? {} : { sizes },
+			...loading === void 0 ? {} : { loading }
+		});
+	};
+}
+/**
+* The component map is built once per process.
+*
+* `createMarkdownComponents` returns fresh component identities on every call,
+* and a new identity for `a` remounts every link in the document on every
+* render — so this memo is correctness, not micro-optimisation.
+*/
+let nextComponents = null;
+function loadNextComponents() {
+	if (nextComponents === null) nextComponents = buildNextComponents().catch((error) => {
+		nextComponents = null;
+		throw error;
+	});
+	return nextComponents;
+}
+async function buildNextComponents() {
+	const [linkMod, imageMod] = await Promise.all([importNext(() => import("next/link"), "next/link"), importNext(() => import("next/image"), "next/image")]);
+	const NextLink = readDefaultExport(linkMod, "next/link");
+	const NextImage = readDefaultExport(imageMod, "next/image");
+	return createMarkdownComponents({
+		Link: wrapNextLink(NextLink),
+		Image: wrapNextImage(NextImage)
+	});
+}
+/**
+* Create the route handlers for a documentation tree.
+*
+* Call it once at module scope in each of the two route files. The filesystem
+* scan, the highlighter and the component map are all shared per process, so
+* the second call is free.
+*/
+function createDocsRoute(options) {
+	const config = resolveDocsConfig(options);
+	const source = createDocsSource(options);
+	const siteUrl = normalizeSiteUrl(options.siteUrl);
+	const contentId = options.contentId ?? "docs-content";
+	const rescanPerRequest = options.rescanPerRequest ?? process.env.NODE_ENV !== "production";
+	let renderer = null;
+	const knownRoutes = /* @__PURE__ */ new Set();
+	let routesLoaded = null;
+	/**
+	* Drop the cached scan so the next query reads the disk again.
+	*
+	* `knownRoutes` is added to, never cleared: it is shared with the renderer,
+	* and emptying it while a concurrent render is asserting links would fail
+	* that page for a link that is perfectly valid. A route left behind by a
+	* deleted page only makes dev *more* permissive than the production build,
+	* which is the right direction to be wrong in.
+	*/
+	const invalidate = () => {
+		source.invalidate();
+		routesLoaded = null;
+	};
+	const loadRoutes = () => routesLoaded ??= source.all().then((files) => {
+		for (const file of files) {
+			knownRoutes.add(file.href);
+			for (const alias of file.frontmatter.aliases ?? []) knownRoutes.add(toAliasRoute(alias, config.basePath, file.relativePath));
+		}
+	});
+	const loadRenderer = () => renderer ??= createDocsRenderer({
+		config,
+		knownRoutes,
+		...options.highlighter === void 0 ? {} : { highlighter: options.highlighter },
+		...options.langs === void 0 ? {} : { langs: options.langs },
+		...options.themes === void 0 ? {} : { themes: options.themes },
+		...options.titleHeading === void 0 ? {} : { titleHeading: options.titleHeading },
+		...options.linkResolver === void 0 ? {} : { linkResolver: options.linkResolver },
+		...options.imageResolver === void 0 ? {} : { imageResolver: options.imageResolver }
+	});
+	/**
+	* `find` returns drafts regardless of config so a preview route can opt in;
+	* a public route must not.
+	*/
+	const findVisible = async (segments) => {
+		if (rescanPerRequest) invalidate();
+		const file = await source.find(segments);
+		if (file === void 0) return;
+		if (!config.includeDrafts && file.frontmatter.draft === true) return;
+		return file;
+	};
+	const getPage = async (segments) => {
+		const file = await findVisible(segments);
+		if (file === void 0) return;
+		await loadRoutes();
+		return loadRenderer().render(file);
+	};
+	const renderAll = async () => {
+		if (rescanPerRequest) invalidate();
+		const files = await source.all();
+		await loadRoutes();
+		const renderer = loadRenderer();
+		return Promise.all(files.map((file) => renderer.render(file)));
+	};
+	async function renderRoute(segments) {
+		const doc = await getPage(segments);
+		if (doc === void 0) return (await loadNotFound())();
+		const components = await loadNextComponents();
+		return createElement("article", {
+			className: "wave-docs-prose",
+			...contentId === false ? {} : {
+				id: contentId,
+				tabIndex: -1
+			}
+		}, createElement(DocContent, {
+			hast: doc.hast,
+			components: {
+				...components,
+				...options.components
+			}
+		}));
+	}
+	return {
+		source,
+		getPage,
+		renderAll,
+		dynamicParams: false,
+		async Page({ params }) {
+			const { slug } = await params;
+			return renderRoute(slug ?? []);
+		},
+		async IndexPage() {
+			return renderRoute([]);
+		},
+		async generateStaticParams() {
+			if (rescanPerRequest) invalidate();
+			return (await source.slugs()).filter((segments) => segments.length > 0).map((segments) => ({ slug: segments }));
+		},
+		async generateMetadata({ params }) {
+			const { slug } = await params;
+			const file = await findVisible(slug ?? []);
+			if (file === void 0) return {};
+			const { title, description } = file.frontmatter;
+			const canonical = siteUrl === void 0 ? file.href : new URL(file.href, siteUrl).toString();
+			return {
+				title,
+				...description === void 0 ? {} : { description },
+				alternates: { canonical },
+				openGraph: {
+					type: "article",
+					title,
+					...description === void 0 ? {} : { description },
+					url: canonical
+				}
+			};
+		}
+	};
+}
+/**
+* Sitemap entries for every published page, for `app/sitemap.ts`.
+*
+* Drafts are excluded, as are aliases — an alias is a redirect, and listing a
+* redirect in a sitemap is a crawl error.
+*
+* ```ts
+* // app/sitemap.ts
+* import { createDocsSitemap } from '@waveso/docs/next';
+*
+* export default async function sitemap() {
+*   return createDocsSitemap({
+*     contentDir: 'content/docs',
+*     siteUrl: 'https://example.com',
+*   });
+* }
+* ```
+*/
+async function createDocsSitemap(options) {
+	const siteUrl = requireSiteUrl(options.siteUrl);
+	const files = await createDocsSource(options).all();
+	const readDate = options.lastModified ?? readMtime;
+	return Promise.all(files.map(async (file) => {
+		const lastModified = await readDate(file);
+		return {
+			url: new URL(file.href, siteUrl).toString(),
+			...lastModified === void 0 ? {} : { lastModified },
+			...options.changeFrequency === void 0 ? {} : { changeFrequency: options.changeFrequency },
+			...options.priority === void 0 ? {} : { priority: options.priority }
+		};
+	}));
+}
+/** Best-effort mtime. A sitemap is not worth failing a build over. */
+async function readMtime(file) {
+	try {
+		return (await stat(file.filePath)).mtime;
+	} catch {
+		return;
+	}
+}
+/**
+* Permanent redirects from every page's `aliases` frontmatter.
+*
+* Renaming a documentation page otherwise breaks every inbound link that ever
+* pointed at it — search results, blog posts, Stack Overflow answers, other
+* people's bookmarks. Adding one line of frontmatter should be the whole cost
+* of a rename.
+*
+* ```ts
+* // next.config.ts
+* import { createDocsRedirects } from '@waveso/docs/next';
+*
+* export default {
+*   redirects: () => createDocsRedirects({ contentDir: 'content/docs' }),
+* };
+* ```
+*
+* Aliases are resolved against the docs base path, so `aliases: ['quickstart']`
+* on `/docs/getting-started` redirects `/docs/quickstart`. Throws when two
+* pages claim the same alias, or when an alias collides with a real page —
+* both silently lose a page otherwise, and both are typos.
+*/
+async function createDocsRedirects(config) {
+	const resolved = resolveDocsConfig(config);
+	const files = await createDocsSource(config).all();
+	const routes = new Map(files.map((file) => [file.href, file]));
+	const claimed = /* @__PURE__ */ new Map();
+	const redirects = [];
+	for (const file of files) for (const alias of file.frontmatter.aliases ?? []) {
+		const route = toAliasRoute(alias, resolved.basePath, file.relativePath);
+		const page = routes.get(route);
+		if (page !== void 0) throw new Error(`@waveso/docs: the alias '${alias}' in ${file.relativePath} redirects '${route}', which is already the route of ${page.relativePath}. Remove the alias, or rename the page it collides with.`);
+		const other = claimed.get(route);
+		if (other !== void 0) throw new Error(`@waveso/docs: '${route}' is claimed as an alias by both ${other.relativePath} and ${file.relativePath}. An alias can only redirect to one page.`);
+		claimed.set(route, file);
+		redirects.push({
+			source: route,
+			destination: file.href,
+			permanent: true
+		});
+	}
+	return redirects;
+}
+function normalizeSiteUrl(siteUrl) {
+	return siteUrl === void 0 ? void 0 : requireSiteUrl(siteUrl);
+}
+/** Fail at config time, not with a malformed `<link rel="canonical">`. */
+function requireSiteUrl(siteUrl) {
+	try {
+		return new URL(siteUrl).toString();
+	} catch {
+		throw new Error(`@waveso/docs: '${siteUrl}' is not an absolute URL. Pass an origin such as 'https://example.com'.`);
+	}
+}
+//#endregion
+export { createDocsRedirects, createDocsRoute, createDocsSitemap };

package/dist/plugins/rehype-capture-toc.d.ts

@@ -0,0 +1,18 @@
+import { TocEntry } from "../types.js";
+import { Plugin } from "unified";
+import { Root } from "hast";
+//#region src/plugins/rehype-capture-toc.d.ts
+declare module 'vfile' {
+  interface DataMap {
+    /** Written by {@link rehypeCaptureToc}. */
+    toc: TocEntry[];
+  }
+}
+/**
+ * rehype plugin. Must run after `rehype-slug`; ordering is enforced by the
+ * renderer rather than checked here, because a heading legitimately may have
+ * been given an id by hand.
+ */
+declare const rehypeCaptureToc: Plugin<[], Root>;
+//#endregion
+export { rehypeCaptureToc };