@minidocs/astro 0.1.0 → 0.2.0

package/README.md

@@ -16,10 +16,24 @@ import { defineConfig } from 'astro/config';
 import minidocs from '@minidocs/astro';
 
 export default defineConfig({
-  integrations: [mdx(), minidocs({ prefix: 'docs' })],
+  integrations: [mdx(), minidocs()],
 });
 ```
 
+```ts
+// src/content.config.ts
+import { defineCollection } from 'astro:content';
+import { z } from 'astro/zod';
+import { glob } from '@minidocs/astro/loaders';
+
+const docs = defineCollection({
+  loader: glob({ base: './src/content/docs', pattern: '**/*.{md,mdx}', prefix: 'docs' }),
+  schema: z.object({ title: z.string() }),
+});
+
+export const collections = { docs };
+```
+
 Requires Astro 7 and Node.js 22.22 or later. See [Getting Started](https://github.com/Ivan-1F/minidocs/blob/main/docs/src/content/docs/en/getting-started.mdx) for the rest of the setup.
 
 ## License

package/dist/index.d.mts

@@ -1,8 +1,6 @@
 import { AstroIntegration } from "astro";
 //#region src/settings.d.ts
 interface MinidocsOptions {
-  /** Path segment the docs live under, e.g. `docs` for `/docs/...`. Defaults to no prefix. */
-  prefix?: string;
   /** Locales to try, in order, when a page is not translated. Locales without an entry never fall back. Requires `i18n`. */
   fallback?: Record<string, string | string[]>;
   /** Markdown syntax minidocs adds on top of the configured processor. */

package/dist/index.mjs

@@ -1,5 +1,5 @@
-import { t as contentOptions } from "./routing-TMqRCY2Q.mjs";
-import { a as renderConfigTypes, i as registry, n as remarkContentLinks, r as satteriContentLinks } from "./links-UTLyoo_o.mjs";
+import { t as contentOptions } from "./routing-D28b92w8.mjs";
+import { a as registry, c as renderConfigTypes, i as namedCollections, n as remarkContentLinks, o as findUnbuiltPages, r as satteriContentLinks } from "./links-Dp7d5R-O.mjs";
 import { existsSync, mkdirSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -175,7 +175,6 @@ function extendProcessor(processor, callouts) {
 const trim = (path) => path.replace(/^\/+|\/+$/g, "");
 function resolveSettings(config, options) {
 	return {
-		prefix: trim(options.prefix ?? ""),
 		base: trim(config.base),
 		trailingSlash: config.trailingSlash === "always" || config.trailingSlash === "ignore" && config.build.format === "directory",
 		i18n: resolveI18n(config.i18n, options),
@@ -208,6 +207,7 @@ const CONFIG_ID = "virtual:minidocs/config";
 const RENDERERS_ID = "virtual:minidocs/renderers";
 function minidocs(options = {}) {
 	let hasMdx = false;
+	let isStatic = false;
 	return {
 		name: "minidocs",
 		hooks: {
@@ -223,13 +223,16 @@ function minidocs(options = {}) {
 						resolveId: (id) => id === CONFIG_ID ? `\0${CONFIG_ID}` : void 0,
 						load: (id) => id === `\0${CONFIG_ID}` ? `export default ${JSON.stringify({
 							...registry.settings,
-							bases: Object.fromEntries(Object.entries(registry.collections).map(([name, { base }]) => [name, base])),
-							pageIds: Object.fromEntries(Object.entries(registry.collections).map(([name, collection]) => [name, pageIds(collection)]))
+							collections: Object.fromEntries(Object.entries(namedCollections()).map(([name, collection]) => [name, {
+								base: collection.base,
+								prefix: collection.prefix,
+								pageIds: pageIds(collection)
+							}]))
 						})};` : void 0
 					}, {
 						name: "minidocs:renderers",
 						resolveId: (id) => id === RENDERERS_ID ? `\0${RENDERERS_ID}` : void 0,
-						load: (id) => id === `\0${RENDERERS_ID}` ? hasMdx ? `import { getContainerRenderer } from '@astrojs/mdx';\nexport default [getContainerRenderer()];` : "export default [];" : void 0
+						load: (id) => id === `\0${RENDERERS_ID}` ? hasMdx ? `import { getContainerRenderer } from '@astrojs/mdx/container-renderer';\nexport default [getContainerRenderer()];` : "export default [];" : void 0
 					}],
 					ssr: { noExternal: ["@minidocs/astro", "@minidocs/core"] }
 				} });
@@ -238,6 +241,7 @@ function minidocs(options = {}) {
 				registry.settings = resolveSettings(config, options);
 				registry.root = fileURLToPath(config.root);
 				hasMdx = config.integrations.some(({ name }) => name === "@astrojs/mdx");
+				isStatic = config.output === "static" && !config.adapter;
 				const injected = injectTypes({
 					filename: "types.d.ts",
 					content: renderConfigTypes(registry.settings)
@@ -248,15 +252,24 @@ function minidocs(options = {}) {
 					mkdirSync(dirname(path), { recursive: true });
 					writeFileSync(path, "export {};\n");
 				}
+			},
+			"astro:build:done"({ pages }) {
+				if (!isStatic || !registry.settings) return;
+				const built = new Set(pages.map(({ pathname }) => pathname.replace(/^\/+|\/+$/g, "")));
+				const missing = findUnbuiltPages(registry.settings, namedCollections(), built);
+				if (missing.length === 0) return;
+				const shown = missing.slice(0, 10).map((page) => `  ${page}`);
+				if (missing.length > shown.length) shown.push(`  and ${missing.length - shown.length} more`);
+				throw new Error(`[minidocs] No route built these pages, so links to them are broken. Check that each collection's route file sits in the folder its prefix names.\n${shown.join("\n")}`);
 			}
 		}
 	};
 }
 /** Ids of every page in a collection, in any locale. */
-function pageIds({ base, filePaths }) {
+function pageIds(collection) {
 	if (!registry.settings) return [];
-	const { locales, localeDirs } = contentOptions(registry.settings, base);
-	return [...new Set(filePaths.map((filePath) => parseFilePath(filePath, base, locales, localeDirs).id))];
+	const { locales, localeDirs } = contentOptions(registry.settings, collection.base);
+	return [...new Set(collection.filePaths.map((filePath) => parseFilePath(filePath, collection.base, locales, localeDirs).id))];
 }
 //#endregion
 export { minidocs as default };

package/dist/{links-UTLyoo_o.mjs → links-Dp7d5R-O.mjs}

@@ -1,4 +1,4 @@
-import { n as href, t as contentOptions } from "./routing-TMqRCY2Q.mjs";
+import { i as markdownHref, n as href, o as routePath, t as contentOptions } from "./routing-D28b92w8.mjs";
 import { existsSync, readFileSync } from "node:fs";
 import { dirname, posix, relative, resolve, sep } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -8,6 +8,14 @@ const union = (values) => {
 	const list = [...new Set(values)].sort().map((value) => JSON.stringify(value));
 	return list.length > 0 ? list.join(" | ") : "never";
 };
+const byName = (collections) => Object.entries(collections).sort(([a], [b]) => a < b ? -1 : 1);
+/** Every page a collection needs a route for, with the locale its URL is built with. */
+function pagesOf(settings, collection) {
+	return listPages(collection.filePaths.map((filePath) => ({ filePath })), contentOptions(settings, collection.base)).map((page) => ({
+		...page,
+		urlLocale: settings.i18n ? page.locale : void 0
+	}));
+}
 /** Renders the site-wide types, known as soon as the config is resolved. */
 function renderConfigTypes(settings) {
 	return [
@@ -27,14 +35,14 @@ function renderTypes(settings, collections) {
 		"declare module '@minidocs/astro/runtime' {",
 		"	interface Collections {"
 	];
-	for (const [name, { base, filePaths }] of Object.entries(collections).sort(([a], [b]) => a < b ? -1 : 1)) {
-		const options = contentOptions(settings, base);
-		const pages = listPages(filePaths.map((filePath) => ({ filePath })), options);
+	for (const [name, collection] of byName(collections)) {
+		const options = contentOptions(settings, collection.base);
+		const pages = pagesOf(settings, collection);
 		const idsAndDirs = (locale) => {
 			const inLocale = pages.filter((page) => page.locale === locale);
 			const dirs = /* @__PURE__ */ new Set([""]);
 			for (const page of inLocale) {
-				const { dir } = parseFilePath(page.entry.filePath, base, options.locales, options.localeDirs);
+				const { dir } = parseFilePath(page.entry.filePath, collection.base, options.locales, options.localeDirs);
 				const segments = dir.split("/").filter(Boolean);
 				for (let i = 1; i <= segments.length; i++) dirs.add(segments.slice(0, i).join("/"));
 			}
@@ -45,7 +53,7 @@ function renderTypes(settings, collections) {
 		};
 		lines.push(`\t\t${JSON.stringify(name)}: {`);
 		if (settings.i18n) {
-			const perLocale = settings.i18n.locales.map((locale) => [JSON.stringify(locale), idsAndDirs(locale)]);
+			const perLocale = options.locales.map((locale) => [JSON.stringify(locale), idsAndDirs(locale)]);
 			lines.push("			pages: {", ...perLocale.map(([locale, { ids }]) => `\t\t\t\t${locale}: ${ids};`), "			};");
 			lines.push("			dirs: {", ...perLocale.map(([locale, { dirs }]) => `\t\t\t\t${locale}: ${dirs};`), "			};");
 		} else {
@@ -57,25 +65,66 @@ function renderTypes(settings, collections) {
 	lines.push("	}", "}", "export {};", "");
 	return lines.join("\n");
 }
+/**
+* Finds pages that would be served at the same URL, across all collections, for HTML pages and Markdown versions alike.
+* Returns one message per pair of files.
+*/
+function findUrlConflicts(settings, collections) {
+	const owners = /* @__PURE__ */ new Map();
+	const conflicts = /* @__PURE__ */ new Map();
+	for (const [name, collection] of byName(collections)) for (const page of pagesOf(settings, collection)) {
+		const owner = `${page.entry.filePath} (${name})`;
+		const urls = [href(settings, collection, page.id, page.urlLocale), markdownHref(settings, collection, page.id, page.urlLocale)];
+		for (const url of urls) {
+			const other = owners.get(url);
+			if (other === void 0) owners.set(url, owner);
+			else if (!conflicts.has(`${other}\n${owner}`)) conflicts.set(`${other}\n${owner}`, `"${url}" is the URL of two pages:\n  ${other}\n  ${owner}`);
+		}
+	}
+	return [...conflicts.values()];
+}
+/**
+* Finds pages that no route generated, given the paths of built pages below `base`.
+* A route file outside the folder that `prefix` names builds its pages elsewhere, and every link to them breaks.
+*/
+function findUnbuiltPages(settings, collections, built) {
+	const missing = [];
+	for (const [name, collection] of byName(collections)) for (const page of pagesOf(settings, collection)) {
+		const path = routePath(settings, collection, page.id, page.urlLocale) ?? "";
+		if (!built.has(path)) missing.push(`/${path} for ${page.entry.filePath} (${name}, prefix "${collection.prefix}")`);
+	}
+	return missing;
+}
 //#endregion
 //#region src/registry.ts
 const key = Symbol.for("minidocs.registry");
 const scope = globalThis;
-scope[key] ??= { collections: {} };
+scope[key] ??= {
+	collections: {},
+	pendingLinks: []
+};
 const registry = scope[key];
+/** Collections whose loader has run, keyed by collection name. */
+function namedCollections() {
+	return Object.fromEntries(Object.values(registry.collections).filter((state) => state.name !== void 0).map((state) => [state.name, state]));
+}
 //#endregion
 //#region src/links.ts
 /** Link to another page from a page in the same locale, relative so it stays in whatever locale the page is shown in. */
-function relativeHref(settings, fromId, toId, locale) {
-	const from = href(settings, fromId, locale);
-	const to = href(settings, toId, locale);
-	const fromDir = from.slice(0, from.lastIndexOf("/") + 1);
-	if (to.endsWith("/")) return `${posix.relative(fromDir, to) || "."}/`;
-	return posix.join(posix.relative(fromDir, posix.dirname(to)), posix.basename(to));
+function relativeHref(settings, from, to, locale) {
+	const fromHref = href(settings, from.collection, from.id, locale);
+	const toHref = href(settings, to.collection, to.id, locale);
+	const fromDir = fromHref.slice(0, fromHref.lastIndexOf("/") + 1);
+	if (toHref.endsWith("/")) return `${posix.relative(fromDir, toHref) || "."}/`;
+	return posix.join(posix.relative(fromDir, posix.dirname(toHref)), posix.basename(toHref));
+}
+/** The collection whose root holds a project-relative file, the innermost one if roots are nested. */
+function collectionOf(collections, file) {
+	return collections.filter(({ base }) => file.startsWith(`${base}/`)).reduce((best, collection) => best && best.base.length > collection.base.length ? best : collection, void 0);
 }
 const EXCLUDED = "points to a page that the collection's filter excludes.";
 /**
-* Rewrites a relative link to a content file into the URL of its page.
+* Rewrites a relative link to a content file, in any collection, into the URL of its page.
 * Links within one locale become relative URLs, so pages shown through fallback keep linking within the shown locale.
 * Returns `undefined` for links that are not to `.md` or `.mdx` files. Throws when the target does not exist.
 */
@@ -85,13 +134,23 @@ function resolveContentLink(settings, source, url, root) {
 	const [, path, hash = ""] = match;
 	const absolute = resolve(root, dirname(source.file), decodeURI(path));
 	const target = relative(root, absolute).split(sep).join("/");
-	if (!target.startsWith(`${source.base}/`)) throw new Error(`"${url}" points outside the content collection, so it has no page.`);
+	const collection = collectionOf(source.collections, target);
+	if (!collection) throw new Error(`"${url}" points outside every collection loaded with minidocs' glob, so it has no page.`);
 	if (!existsSync(absolute)) throw new Error(`"${url}" points to a file that does not exist.`);
-	if (source.isExcluded?.(target)) throw new Error(`"${url}" ${EXCLUDED}`);
-	const { locales, localeDirs } = contentOptions(settings, source.base);
-	const from = parseFilePath(source.file, source.base, locales, localeDirs);
-	const to = parseFilePath(target, source.base, locales, localeDirs);
-	return (from.locale === to.locale ? relativeHref(settings, from.id, to.id, settings.i18n ? from.locale : void 0) : href(settings, to.id, to.locale)) + hash;
+	if (source.isExcluded?.(target, collection)) throw new Error(`"${url}" ${EXCLUDED}`);
+	const parse = (file, of) => {
+		const { locales, localeDirs } = contentOptions(settings, of.base);
+		return parseFilePath(file, of.base, locales, localeDirs);
+	};
+	const from = parse(source.file, source.collection);
+	const to = parse(target, collection);
+	return (from.locale === to.locale ? relativeHref(settings, {
+		collection: source.collection,
+		id: from.id
+	}, {
+		collection,
+		id: to.id
+	}, settings.i18n ? from.locale : void 0) : href(settings, collection, to.id, to.locale)) + hash;
 }
 /**
 * Resolves a link found in a Markdown file, or returns `undefined` to leave it alone.
@@ -101,30 +160,36 @@ function rewrite(filePath, url) {
 	const { settings, root } = registry;
 	if (!settings || !root) return void 0;
 	const file = relative(root, filePath).split(sep).join("/");
-	const collection = Object.values(registry.collections).find(({ base }) => file.startsWith(`${base}/`));
+	const collections = Object.values(registry.collections);
+	const collection = collectionOf(collections, file);
 	if (!collection) return void 0;
-	const isExcluded = (target) => {
-		if (collection.loading) {
-			collection.pendingLinks.push({
+	const ready = (state) => state.loaded && !state.loading;
+	const isExcluded = (target, to) => {
+		if (!ready(collection) || !ready(to)) {
+			registry.pendingLinks.push({
 				file,
 				url,
-				target
+				target,
+				source: collection,
+				to
 			});
 			return false;
 		}
-		return collection.excluded.has(target);
+		return to.excluded.has(target);
 	};
 	return resolveContentLink(settings, {
 		file,
-		base: collection.base,
+		collection,
+		collections,
 		isExcluded
 	}, url, root);
 }
-/** Checks links that Markdown rendered during a load, now that every entry has been filtered. */
-function checkPendingLinks(collection) {
-	const pending = collection.pendingLinks;
-	collection.pendingLinks = [];
-	const broken = pending.filter(({ file, target }) => !collection.excluded.has(file) && collection.excluded.has(target));
+/** Checks links rendered while a collection involved was loading, once both collections have loaded. */
+function checkPendingLinks() {
+	const ready = (state) => state.loaded && !state.loading;
+	const due = registry.pendingLinks.filter(({ source, to }) => ready(source) && ready(to));
+	registry.pendingLinks = registry.pendingLinks.filter((link) => !due.includes(link));
+	const broken = due.filter(({ file, target, source, to }) => !source.excluded.has(file) && to.excluded.has(target));
 	if (broken.length === 0) return;
 	const root = registry.root ?? "";
 	throw new Error(broken.map(({ file, url }) => failure(resolve(root, file), url, /* @__PURE__ */ new Error(`"${url}" ${EXCLUDED}`)).message).join("\n"));
@@ -174,4 +239,4 @@ function remarkContentLinks() {
 	};
 }
 //#endregion
-export { renderConfigTypes as a, registry as i, remarkContentLinks as n, renderTypes as o, satteriContentLinks as r, checkPendingLinks as t };
+export { registry as a, renderConfigTypes as c, namedCollections as i, renderTypes as l, remarkContentLinks as n, findUnbuiltPages as o, satteriContentLinks as r, findUrlConflicts as s, checkPendingLinks as t };

package/dist/loaders.d.mts

@@ -7,14 +7,19 @@ export interface FilterEntry {
   data: Record<string, unknown>;
   filePath?: string | undefined;
 }
+export interface MinidocsGlobOptions {
+  /** Path segment the pages live under, e.g. `docs` for `/docs/...`. Defaults to the site root. */
+  prefix?: string;
+  /** Entries for which it returns `false` never reach the collection. */
+  filter?: (entry: FilterEntry) => boolean;
+}
 /**
- * Astro's `glob()` loader, plus recording of the collection root so minidocs can
- * derive locales and page ids, and generate types for them.
+ * Astro's `glob()` loader, plus recording of the collection root and URL prefix so minidocs can
+ * derive locales, page ids and URLs, and generate types for them.
  * Entries rejected by `filter` never reach the collection, so types, links and pages all agree on what exists.
  */
-export declare function glob({ filter, ...options }: GlobOptions & {
+export declare function glob({ prefix, filter, ...options }: GlobOptions & {
   base: string | URL;
-  filter?: (entry: FilterEntry) => boolean;
-}): Loader;
+} & MinidocsGlobOptions): Loader;
 //#endregion
 export {};

package/dist/loaders.mjs

@@ -1,36 +1,43 @@
-import { i as registry, o as renderTypes, t as checkPendingLinks } from "./links-UTLyoo_o.mjs";
+import { a as registry, i as namedCollections, l as renderTypes, s as findUrlConflicts, t as checkPendingLinks } from "./links-Dp7d5R-O.mjs";
 import { mkdirSync, writeFileSync } from "node:fs";
-import { dirname, relative } from "node:path";
+import { dirname, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { glob as glob$1 } from "astro/loaders";
 //#region src/loaders.ts
+/** Collection root relative to the project, as Astro's glob resolves `base`. */
+const relativeBase = (base, root) => relative(root, base instanceof URL ? fileURLToPath(base) : resolve(root, base)).replaceAll("\\", "/");
+function register(base, declared) {
+	registry.collections[base] ??= {
+		base,
+		...declared,
+		filePaths: [],
+		excluded: /* @__PURE__ */ new Set(),
+		loading: false,
+		loaded: false
+	};
+	return Object.assign(registry.collections[base], declared);
+}
 /**
-* Astro's `glob()` loader, plus recording of the collection root so minidocs can
-* derive locales and page ids, and generate types for them.
+* Astro's `glob()` loader, plus recording of the collection root and URL prefix so minidocs can
+* derive locales, page ids and URLs, and generate types for them.
 * Entries rejected by `filter` never reach the collection, so types, links and pages all agree on what exists.
 */
-function glob({ filter, ...options }) {
+function glob({ prefix = "", filter, ...options }) {
 	const inner = glob$1(options);
+	const declared = { prefix: prefix.replace(/^\/+|\/+$/g, "") };
+	if (registry.root) register(relativeBase(options.base, registry.root), declared);
 	return {
 		...inner,
 		name: "minidocs-glob",
 		async load(context) {
-			const baseUrl = options.base instanceof URL ? options.base : new URL(options.base, context.config.root);
-			const base = relative(fileURLToPath(context.config.root), fileURLToPath(baseUrl)).replaceAll("\\", "/");
+			const state = register(relativeBase(options.base, fileURLToPath(context.config.root)), declared);
+			if (state.name !== void 0 && state.name !== context.collection) throw new Error(`[minidocs] Collections "${state.name}" and "${context.collection}" are both loaded from ${state.base}.`);
+			state.name = context.collection;
 			let scheduled;
 			const update = () => {
 				clearTimeout(scheduled);
-				scheduled = setTimeout(() => writeTypes(context), 50);
-			};
-			registry.collections[context.collection] ??= {
-				base,
-				filePaths: [],
-				excluded: /* @__PURE__ */ new Set(),
-				loading: false,
-				pendingLinks: []
+				scheduled = setTimeout(() => writeTypes(context, state, (message) => context.logger.error(message)), 50);
 			};
-			const state = registry.collections[context.collection];
-			state.base = base;
 			const store = new Proxy(context.store, { get(target, property, receiver) {
 				const value = Reflect.get(target, property, receiver);
 				if (property !== "set" && property !== "delete" && property !== "clear") return value;
@@ -57,20 +64,25 @@ function glob({ filter, ...options }) {
 			} finally {
 				state.loading = false;
 			}
+			state.loaded = true;
 			clearTimeout(scheduled);
-			writeTypes(context);
-			checkPendingLinks(state);
+			writeTypes(context, state, (message) => {
+				throw new Error(message);
+			});
+			checkPendingLinks();
 		}
 	};
 }
-function writeTypes(context) {
+function writeTypes(context, state, report) {
 	const { settings, typesFile } = registry;
 	if (!settings || !typesFile) throw new Error("[minidocs] Add the minidocs() integration to your Astro config to use glob from '@minidocs/astro/loaders'.");
-	const filePaths = context.store.values().map((entry) => entry.filePath).filter((filePath) => Boolean(filePath));
-	registry.collections[context.collection].filePaths = filePaths;
+	state.filePaths = context.store.values().map((entry) => entry.filePath).filter((filePath) => Boolean(filePath));
+	const collections = namedCollections();
 	const path = fileURLToPath(typesFile);
 	mkdirSync(dirname(path), { recursive: true });
-	writeFileSync(path, renderTypes(settings, registry.collections));
+	writeFileSync(path, renderTypes(settings, collections));
+	const conflicts = findUrlConflicts(settings, collections);
+	if (conflicts.length > 0) report(conflicts.map((conflict) => `[minidocs] ${conflict}`).join("\n"));
 }
 //#endregion
 export { glob };

package/dist/routing-D28b92w8.mjs

@@ -0,0 +1,60 @@
+//#region src/routing.ts
+/** The locale every page of a single-language site belongs to inside core. Never exposed to users. */
+const SINGLE_LOCALE = "default";
+/** Options for core: locale directories for multilingual sites, one implicit locale otherwise. */
+function contentOptions(settings, base) {
+	return settings.i18n ? {
+		base,
+		locales: settings.i18n.locales,
+		fallback: settings.i18n.fallback
+	} : {
+		base,
+		locales: [SINGLE_LOCALE],
+		localeDirs: false
+	};
+}
+/** The URL segment of a page id: the root index page has none. */
+function slugOf(id) {
+	return id === "index" ? "" : id;
+}
+const normalizeLocale = (locale) => locale.replaceAll("_", "-").toLowerCase();
+/** The URL segment of a locale, `undefined` for the default locale when it is not prefixed, as rest parameters expect. */
+function localeParam(settings, locale) {
+	const { i18n } = settings;
+	if (!i18n || locale === void 0 || locale === i18n.defaultLocale && !i18n.prefixDefaultLocale) return void 0;
+	return normalizeLocale(locale);
+}
+/**
+* Path of a page below `base`, e.g. `en/docs/getting-started`, without slashes around it.
+* `undefined` stands for the site root.
+*/
+function routePath(settings, collection, id, locale) {
+	return [
+		localeParam(settings, locale),
+		collection.prefix,
+		slugOf(id)
+	].filter(Boolean).join("/") || void 0;
+}
+/** Link to a page, including `base` and the trailing slash Astro would use. */
+function href(settings, collection, id, locale) {
+	const path = [settings.base, routePath(settings, collection, id, locale)].filter(Boolean).join("/");
+	if (!path) return "/";
+	return `/${path}${settings.trailingSlash ? "/" : ""}`;
+}
+/**
+* Path of the Markdown version of a page below the locale segment, e.g. `docs/getting-started`.
+* The root of a site without a prefix has no segment of its own, so it becomes `index`.
+*/
+function markdownPath(collection, id) {
+	return [collection.prefix, slugOf(id)].filter(Boolean).join("/") || "index";
+}
+/** Link to the Markdown version of a page, including `base`. */
+function markdownHref(settings, collection, id, locale) {
+	return `/${[
+		settings.base,
+		localeParam(settings, locale),
+		markdownPath(collection, id)
+	].filter(Boolean).join("/")}.md`;
+}
+//#endregion
+export { markdownPath as a, markdownHref as i, href as n, routePath as o, localeParam as r, slugOf as s, contentOptions as t };

package/dist/runtime.d.mts

@@ -20,6 +20,8 @@ type IsI18n = Config extends {
 export type Locale = Config extends {
   locale: infer L extends string;
 } ? L : string;
+/** Names of the collections loaded with minidocs' glob, or any string before their types are generated. */
+export type CollectionName = [keyof Collections] extends [never] ? string : Extract<keyof Collections, string>;
 type Known<C extends string> = C extends keyof Collections ? Collections[C] : never;
 type Lookup<T, L> = T extends string ? T : L extends keyof T ? Extract<T[L], string> : never;
 type Field<C extends string, K extends string, L> = [Known<C>] extends [never] ? string : Known<C> extends Record<K, infer T> ? Lookup<T, L> : string;
@@ -73,15 +75,29 @@ export type DocTree<E extends DocEntry> = IsI18n extends true ? Record<Locale, D
 interface PageInfo<E extends DocEntry> {
   id: Id<E>;
   entry: E;
-  /** Route parameter for `src/pages/[...path].astro`. `undefined` is the site root. */
-  path: string | undefined;
+  /** Route parameters for `src/pages/docs/[...slug].astro`. `slug` is `undefined` for the root page of the collection. */
+  params: {
+    slug: string | undefined;
+  };
   href: string;
-  /** Route parameter for `src/pages/[...path].md.ts`. */
-  markdownPath: string;
+  /** Route parameters for `src/pages/[...path].md.ts`, which serves the Markdown versions of every collection. */
+  markdownParams: {
+    path: string;
+  };
   /** Link to the Markdown version of the page. */
   markdownHref: string;
 }
 interface LocalizedPageInfo<E extends DocEntry> extends PageInfo<E> {
+  /** Route parameters for `src/pages/[...locale]/docs/[...slug].astro`. `locale` is `undefined` for the default locale when it is not prefixed. */
+  params: {
+    locale: string | undefined;
+    slug: string | undefined;
+  };
+  /** Route parameters for `src/pages/[...locale]/[...path].md.ts`, which serves the Markdown versions of every collection. */
+  markdownParams: {
+    locale: string | undefined;
+    path: string;
+  };
   /** Locale the page is shown in. */
   locale: Locale;
   /** Locale the content comes from. Differs from `locale` only for fallback pages. */
@@ -97,10 +113,13 @@ export type DocPage<E extends DocEntry> = IsI18n extends true ? LocalizedPageInf
 type LocaleArgs = IsI18n extends true ? [locale: Locale] : [];
 /** Builds the navigation tree. Multilingual sites get one tree per locale, built by running `build` once for each. */
 export declare function defineTree<E extends DocEntry>(entries: readonly E[], build: (context: BuildContext<E>) => DocNode<E>[] | Promise<DocNode<E>[]>): Promise<DocTree<E>>;
-/** Link to a page, including `base` and the trailing slash Astro would use. */
-export declare function toHref(id: string, ...locale: LocaleArgs): string;
-/** Route parameter for a page in `src/pages/[...path].astro`. `undefined` is the site root. */
-export declare function toPath(id: string, ...locale: LocaleArgs): string | undefined;
+/** Link to a page, including `base` and the trailing slash Astro would use. Multilingual sites take a locale. */
+export declare function toHref<C extends CollectionName>(collection: C, id: PageIdOf<C>, ...locale: LocaleArgs): string;
+/**
+ * The `[...locale]` route parameter of a locale, for the site's own pages such as a home page or a 404 page.
+ * `undefined` for the default locale when it is not prefixed.
+ */
+export declare function toLocaleParam(locale: Locale): string | undefined;
 /** Whether a component renders for the Markdown version of a page, where it should output plain HTML that converts cleanly. */
 export declare function isMarkdown(astro: {
   locals: object;
@@ -122,23 +141,46 @@ export type MarkdownPage<E extends DocEntry> = IsI18n extends true ? {
  * Renders the content of a page and converts it into Markdown for agents, without a title.
  * Components can check `isMarkdown(Astro)` to render a form that converts cleanly.
  */
-export declare function toMarkdown<E extends DocEntry>(page: MarkdownPage<E>, options?: MarkdownOptions): Promise<string>;
+export declare function toMarkdown(page: MarkdownPage<DocEntry>, options?: MarkdownOptions): Promise<string>;
+/** A node of a tree from any collection, so trees of several collections can be joined into one file. */
+interface TreeNode {
+  label: string;
+  page?: {
+    id: string;
+    entry: DocEntry;
+  } | undefined;
+  href?: string | undefined;
+  children: readonly TreeNode[];
+}
+/**
+ * Entries of every collection found in a tree, which may join trees of several collections.
+ * A tree node is structurally the same as a group wrapping it, so the walk stops at a fixed depth instead.
+ */
+type EntryOf<N, Depth extends unknown[] = []> = Depth['length'] extends 4 ? never : N extends {
+  page?: infer P;
+  children: readonly (infer C)[];
+} ? (P extends {
+  entry: infer E;
+} ? E : never) | EntryOf<C, [...Depth, unknown]> : never;
 /**
  * Renders a tree as llms.txt. Top-level pages come first, every top-level node with children becomes a section,
  * and links point to the Markdown versions of pages. The `index` page's description becomes the summary.
  */
-export declare function toLlmsTxt<E extends DocEntry>(nodes: DocNode<E>[], options: LlmsTxtOptions<E>): string;
+export declare function toLlmsTxt<N extends TreeNode>(nodes: readonly N[], options: LlmsTxtOptions<EntryOf<N>>): string;
 /**
  * Every page of a tree in reading order, as Markdown under its title and source URL, for llms-full.txt.
  * Like llms.txt, links and images are full URLs when `site` is set.
  */
-export declare function toLlmsFullTxt<E extends DocEntry>(nodes: DocNode<E>[], options?: MarkdownOptions): Promise<string>;
+export declare function toLlmsFullTxt<N extends TreeNode>(nodes: readonly N[], options?: MarkdownOptions): Promise<string>;
 /** Every page that needs a route. Multilingual sites include every locale and untranslated pages served through fallback. */
 export declare function listPages<E extends DocEntry>(entries: readonly E[]): DocPage<E>[];
 interface NavNode {
   page?: {
     id: string;
     locale?: string;
+    entry: {
+      collection: string;
+    };
   } | undefined;
   href?: string | undefined;
   children: NavNode[];

package/dist/runtime.mjs

@@ -1,4 +1,4 @@
-import { a as routePath, i as markdownPath, n as href, r as markdownHref, t as contentOptions } from "./routing-TMqRCY2Q.mjs";
+import { a as markdownPath, i as markdownHref, n as href, r as localeParam, s as slugOf, t as contentOptions } from "./routing-D28b92w8.mjs";
 import { MissingPageError, createTree, findPath, listPages as listPages$1, navState as navState$1, neighbors, tocTree } from "@minidocs/core";
 import config from "virtual:minidocs/config";
 import { fromHtml } from "hast-util-from-html";
@@ -8,11 +8,12 @@ import { toMarkdown as toMarkdown$1 } from "mdast-util-to-markdown";
 //#region src/llms.ts
 const escapeLabel = (text) => text.replace(/[[\]\\]/g, "\\$&");
 const oneLine = (text) => text.replace(/\s+/g, " ").trim();
-/** Pages of a tree in reading order, each page once. */
+/** Pages of a tree in reading order, each page once. Trees of several collections can be joined, so a page is its collection and id. */
 function pagesInOrder(nodes) {
 	const pages = /* @__PURE__ */ new Map();
 	const visit = (node) => {
-		if (node.page && !pages.has(node.page.id)) pages.set(node.page.id, node.page);
+		const key = node.page && `${node.page.entry.collection}\0${node.page.id}`;
+		if (key && !pages.has(key)) pages.set(key, node.page);
 		node.children.forEach(visit);
 	};
 	nodes.forEach(visit);
@@ -149,13 +150,16 @@ function htmlToMarkdown(html, context) {
 }
 //#endregion
 //#region src/runtime.ts
-function optionsFor(entries) {
-	const collection = entries[0]?.collection;
-	if (!collection) throw new Error("[minidocs] Expected at least one entry.");
-	const base = config.bases[collection];
-	if (base === void 0) throw new Error(`[minidocs] Collection "${collection}" must be loaded with glob from '@minidocs/astro/loaders'.`);
-	if (entries.some((entry) => entry.collection !== collection)) throw new Error("[minidocs] All entries must come from the same collection.");
-	return contentOptions(config, base);
+function collectionNamed(name) {
+	const collection = config.collections[name];
+	if (!collection) throw new Error(`[minidocs] Collection "${name}" must be loaded with glob from '@minidocs/astro/loaders'.`);
+	return collection;
+}
+function collectionOf(entries) {
+	const name = entries[0]?.collection;
+	if (!name) throw new Error("[minidocs] Expected at least one entry.");
+	if (entries.some((entry) => entry.collection !== name)) throw new Error("[minidocs] All entries must come from the same collection.");
+	return collectionNamed(name);
 }
 /** Drops locale details from nodes of single-language sites, where they carry no meaning. */
 function withoutLocale(nodes) {
@@ -170,7 +174,8 @@ function withoutLocale(nodes) {
 }
 /** Builds the navigation tree. Multilingual sites get one tree per locale, built by running `build` once for each. */
 async function defineTree(entries, build) {
-	const options = optionsFor(entries);
+	const collection = collectionOf(entries);
+	const options = contentOptions(config, collection.base);
 	const run = build;
 	let tree;
 	try {
@@ -179,18 +184,22 @@ async function defineTree(entries, build) {
 			label: (entry) => entry.data.title
 		}, config.i18n ? run : ({ locale: _, ...helpers }) => run(helpers));
 	} catch (error) {
-		if (error instanceof MissingPageError && config.pageIds[entries[0].collection]?.includes(error.id)) throw new Error(`[minidocs] Page "${error.id}" is in the collection but not among the entries passed to defineTree. To leave pages out, use the filter option of glob from '@minidocs/astro/loaders' instead of filtering the entries.`, { cause: error });
+		if (error instanceof MissingPageError && collection.pageIds.includes(error.id)) throw new Error(`[minidocs] Page "${error.id}" is in the collection but not among the entries passed to defineTree. To leave pages out, use the filter option of glob from '@minidocs/astro/loaders' instead of filtering the entries.`, { cause: error });
 		throw error;
 	}
 	return config.i18n ? tree : withoutLocale(tree[options.locales[0]]);
 }
-/** Link to a page, including `base` and the trailing slash Astro would use. */
-function toHref(id, ...locale) {
-	return href(config, id, locale[0]);
+/** Link to a page, including `base` and the trailing slash Astro would use. Multilingual sites take a locale. */
+function toHref(collection, id, ...locale) {
+	return href(config, collectionNamed(collection), id, locale[0]);
 }
-/** Route parameter for a page in `src/pages/[...path].astro`. `undefined` is the site root. */
-function toPath(id, ...locale) {
-	return routePath(config, id, locale[0]);
+/**
+* The `[...locale]` route parameter of a locale, for the site's own pages such as a home page or a 404 page.
+* `undefined` for the default locale when it is not prefixed.
+*/
+function toLocaleParam(locale) {
+	if (!config.i18n) throw new Error("[minidocs] toLocaleParam requires `i18n` in your Astro config.");
+	return localeParam(config, locale);
 }
 const MARKDOWN = "minidocs:markdown";
 /** Whether a component renders for the Markdown version of a page, where it should output plain HTML that converts cleanly. */
@@ -212,16 +221,17 @@ async function containerFor(extra) {
 	}
 	return container;
 }
-const markdownPages = /* @__PURE__ */ new Map();
-/** Markdown versions of every page in a collection, keyed by the URL path of the HTML page. */
-function markdownPagesOf(collection) {
-	let pages = markdownPages.get(collection);
-	if (!pages) {
-		pages = /* @__PURE__ */ new Map();
-		for (const id of config.pageIds[collection] ?? []) for (const locale of config.i18n?.locales ?? [void 0]) pages.set(pathKey(href(config, id, locale)), markdownHref(config, id, locale));
-		markdownPages.set(collection, pages);
+let markdownPages;
+/** Markdown versions of every page on the site, keyed by the URL path of the HTML page, so links into any collection convert. */
+function markdownPagesOnSite() {
+	if (!markdownPages) {
+		markdownPages = /* @__PURE__ */ new Map();
+		for (const collection of Object.values(config.collections)) {
+			const locales = config.i18n?.locales ?? [void 0];
+			for (const id of collection.pageIds) for (const locale of locales) markdownPages.set(pathKey(href(config, collection, id, locale)), markdownHref(config, collection, id, locale));
+		}
 	}
-	return pages;
+	return markdownPages;
 }
 /** Full URL of a path when `site` is set, for text that is often pasted where paths do not resolve. */
 const fullUrl = (path) => config.site ? new URL(path, config.site).href : path;
@@ -246,12 +256,12 @@ async function renderMarkdown(page, options, resolve) {
 		throw error;
 	}
 	return htmlToMarkdown(html, {
-		pageHref: href(config, id, locale),
-		markdownOf: (path) => markdownPagesOf(entry.collection).get(path),
+		pageHref: href(config, collectionNamed(entry.collection), id, locale),
+		markdownOf: (path) => markdownPagesOnSite().get(path),
 		resolve
 	});
 }
-const markdownUrl = ({ id, locale }) => fullUrl(markdownHref(config, id, locale));
+const markdownUrl = ({ id, locale, entry }) => fullUrl(markdownHref(config, collectionNamed(entry.collection), id, locale));
 /**
 * Renders a tree as llms.txt. Top-level pages come first, every top-level node with children becomes a section,
 * and links point to the Markdown versions of pages. The `index` page's description becomes the summary.
@@ -269,30 +279,37 @@ async function toLlmsFullTxt(nodes, options = {}) {
 }
 /** Every page that needs a route. Multilingual sites include every locale and untranslated pages served through fallback. */
 function listPages(entries) {
-	const pages = listPages$1(entries, optionsFor(entries));
+	const collection = collectionOf(entries);
+	const pages = listPages$1(entries, contentOptions(config, collection.base));
 	if (!config.i18n) return pages.map(({ id, entry }) => ({
 		id,
 		entry,
-		path: routePath(config, id),
-		href: href(config, id),
-		markdownPath: markdownPath(config, id),
-		markdownHref: markdownHref(config, id)
+		params: { slug: slugOf(id) || void 0 },
+		href: href(config, collection, id),
+		markdownParams: { path: markdownPath(collection, id) },
+		markdownHref: markdownHref(config, collection, id)
 	}));
 	const alternates = /* @__PURE__ */ new Map();
 	for (const page of pages) {
 		const list = alternates.get(page.id) ?? [];
 		list.push({
 			locale: page.locale,
-			href: href(config, page.id, page.locale)
+			href: href(config, collection, page.id, page.locale)
 		});
 		alternates.set(page.id, list);
 	}
 	return pages.map((page) => ({
 		...page,
-		path: routePath(config, page.id, page.locale),
-		href: href(config, page.id, page.locale),
-		markdownPath: markdownPath(config, page.id, page.locale),
-		markdownHref: markdownHref(config, page.id, page.locale),
+		params: {
+			locale: localeParam(config, page.locale),
+			slug: slugOf(page.id) || void 0
+		},
+		href: href(config, collection, page.id, page.locale),
+		markdownParams: {
+			locale: localeParam(config, page.locale),
+			path: markdownPath(collection, page.id)
+		},
+		markdownHref: markdownHref(config, collection, page.id, page.locale),
 		alternates: alternates.get(page.id)
 	}));
 }
@@ -301,10 +318,10 @@ function navState(nodes, id) {
 	const state = navState$1(nodes, id);
 	return { of(node) {
 		return {
-			href: node.page ? href(config, node.page.id, node.page.locale) : node.href,
+			href: node.page ? href(config, collectionNamed(node.page.entry.collection), node.page.id, node.page.locale) : node.href,
 			...state.of(node)
 		};
 	} };
 }
 //#endregion
-export { defineTree, findPath, isMarkdown, listPages, navState, neighbors, toHref, toLlmsFullTxt, toLlmsTxt, toMarkdown, toPath, tocTree };
+export { defineTree, findPath, isMarkdown, listPages, navState, neighbors, toHref, toLlmsFullTxt, toLlmsTxt, toLocaleParam, toMarkdown, tocTree };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@minidocs/astro",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Astro integration for building documentation sites from composable primitives",
   "keywords": [
     "astro",
@@ -58,7 +58,7 @@
     "mdast-util-gfm": "^3.1.0",
     "mdast-util-to-markdown": "^2.2.0",
     "remark-directive": "^4.0.0",
-    "@minidocs/core": "^0.1.0"
+    "@minidocs/core": "0.2.0"
   },
   "devDependencies": {
     "@types/hast": "^3.0.5",

package/src/styles/base.css

@@ -7,7 +7,8 @@
     --md-color-text: light-dark(#3f3f46, #d4d4d8);
     --md-color-muted: light-dark(#71717a, #a1a1aa);
     --md-color-border: light-dark(#e4e4e7, #2e2e33);
-    --md-color-accent: light-dark(#0b7a6e, #4fd1bf);
+    /* Neutral by default, so a site brings its own color by setting this one variable */
+    --md-color-accent: var(--md-color-heading);
     --md-color-hover: color-mix(in srgb, var(--md-color-heading) 5%, transparent);
     --md-color-current: color-mix(in srgb, var(--md-color-accent) 9%, transparent);
     --md-color-code-bg: light-dark(#f6f6f7, #202024);

package/src/styles/pager.css

@@ -9,24 +9,34 @@
     border-block-start: 1px solid var(--md-color-border);
   }
 
+  /* Padding gives hover a background like the sidebar's, and margins on the outer side keep text aligned */
   .md-pager-link {
     display: flex;
     flex-direction: column;
     gap: 0.125rem;
+    margin-block: -0.5rem;
+    margin-inline: -0.75rem 0;
+    padding: 0.5rem 0.75rem;
+    border-radius: var(--md-radius);
     color: var(--md-color-heading);
     text-decoration: none;
+    transition: background-color 0.15s;
+  }
+
+  .md-pager-link:hover {
+    background: var(--md-color-hover);
   }
 
   /* The next page stays on the end side even when there is no previous one */
   .md-pager-link[rel="next"] {
     grid-column: 2;
+    margin-inline: 0 -0.75rem;
     text-align: end;
   }
 
   .md-pager-link:focus-visible {
-    border-radius: 2px;
     outline: var(--md-focus-ring);
-    outline-offset: 4px;
+    outline-offset: -2px;
   }
 
   .md-pager-label {
@@ -36,15 +46,10 @@
 
   .md-pager-title {
     font-weight: 500;
-    transition: color 0.15s;
-  }
-
-  .md-pager-link:hover .md-pager-title {
-    color: var(--md-color-accent);
   }
 
   @media (prefers-reduced-motion: reduce) {
-    .md-pager-title {
+    .md-pager-link {
       transition: none;
     }
   }

package/src/styles/search.css

@@ -151,9 +151,14 @@
     background: var(--md-color-hover);
   }
 
+  /* The underline keeps matches visible even when the accent is the heading color */
   .md-search-results mark {
     background: none;
     color: var(--md-color-accent);
+    text-decoration: underline;
+    text-decoration-color: color-mix(in srgb, var(--md-color-accent) 50%, transparent);
+    text-decoration-thickness: 1px;
+    text-underline-offset: 0.2em;
   }
 
   .md-search-idle,

package/dist/routing-TMqRCY2Q.mjs

@@ -1,48 +0,0 @@
-//#region src/routing.ts
-/** The locale every page of a single-language site belongs to inside core. Never exposed to users. */
-const SINGLE_LOCALE = "default";
-/** Options for core: locale directories for multilingual sites, one implicit locale otherwise. */
-function contentOptions(settings, base) {
-	return settings.i18n ? {
-		base,
-		locales: settings.i18n.locales,
-		fallback: settings.i18n.fallback
-	} : {
-		base,
-		locales: [SINGLE_LOCALE],
-		localeDirs: false
-	};
-}
-/** The URL segment of a page id: the root index page has none. */
-function slugOf(id) {
-	return id === "index" ? "" : id;
-}
-const normalizeLocale = (locale) => locale.replaceAll("_", "-").toLowerCase();
-/**
-* Route parameter for a page, e.g. `en/docs/getting-started`, without `base` or slashes around it.
-* `undefined` stands for the site root, as Astro expects for rest parameters.
-*/
-function routePath(settings, id, locale) {
-	const { i18n } = settings;
-	return [
-		!i18n || locale === void 0 || locale === i18n.defaultLocale && !i18n.prefixDefaultLocale ? "" : normalizeLocale(locale),
-		settings.prefix,
-		slugOf(id)
-	].filter(Boolean).join("/") || void 0;
-}
-/** Link to a page, including `base` and the trailing slash Astro would use. */
-function href(settings, id, locale) {
-	const path = [settings.base, routePath(settings, id, locale)].filter(Boolean).join("/");
-	if (!path) return "/";
-	return `/${path}${settings.trailingSlash ? "/" : ""}`;
-}
-/** Route parameter for a page in `src/pages/[...path].md.ts`. The site root has no segment of its own, so it becomes `index`. */
-function markdownPath(settings, id, locale) {
-	return routePath(settings, id, locale) ?? "index";
-}
-/** Link to the Markdown version of a page, including `base`. */
-function markdownHref(settings, id, locale) {
-	return `/${[settings.base, markdownPath(settings, id, locale)].filter(Boolean).join("/")}.md`;
-}
-//#endregion
-export { routePath as a, markdownPath as i, href as n, markdownHref as r, contentOptions as t };