@waveso/docs 0.1.0

package/dist/highlighter.d.ts

@@ -0,0 +1,99 @@
+import { createHighlighterCore } from "shiki/core";
+//#region src/highlighter.d.ts
+/** A ready-to-use Shiki highlighter carrying only the docs grammars. */
+type DocsHighlighter = Awaited<ReturnType<typeof createHighlighterCore>>;
+declare const LANG_LOADERS: {
+  typescript: () => Promise<typeof import("@shikijs/langs/typescript")>;
+  ts: () => Promise<typeof import("@shikijs/langs/typescript")>;
+  tsx: () => Promise<typeof import("@shikijs/langs/tsx")>;
+  javascript: () => Promise<typeof import("@shikijs/langs/javascript")>;
+  js: () => Promise<typeof import("@shikijs/langs/javascript")>;
+  jsx: () => Promise<typeof import("@shikijs/langs/jsx")>;
+  json: () => Promise<typeof import("@shikijs/langs/json")>;
+  shellscript: () => Promise<typeof import("@shikijs/langs/shellscript")>;
+  bash: () => Promise<typeof import("@shikijs/langs/shellscript")>;
+  sh: () => Promise<typeof import("@shikijs/langs/shellscript")>;
+  shell: () => Promise<typeof import("@shikijs/langs/shellscript")>;
+  zsh: () => Promise<typeof import("@shikijs/langs/shellscript")>;
+  css: () => Promise<typeof import("@shikijs/langs/css")>;
+  html: () => Promise<typeof import("@shikijs/langs/html")>;
+  markdown: () => Promise<typeof import("@shikijs/langs/markdown")>;
+  md: () => Promise<typeof import("@shikijs/langs/markdown")>;
+  yaml: () => Promise<typeof import("@shikijs/langs/yaml")>;
+  yml: () => Promise<typeof import("@shikijs/langs/yaml")>;
+  diff: () => Promise<typeof import("@shikijs/langs/diff")>;
+  sql: () => Promise<typeof import("@shikijs/langs/sql")>;
+  python: () => Promise<typeof import("@shikijs/langs/python")>;
+  py: () => Promise<typeof import("@shikijs/langs/python")>;
+  go: () => Promise<typeof import("@shikijs/langs/go")>;
+  rust: () => Promise<typeof import("@shikijs/langs/rust")>;
+  rs: () => Promise<typeof import("@shikijs/langs/rust")>;
+  prisma: () => Promise<typeof import("@shikijs/langs/prisma")>;
+  ini: () => import("shiki").Awaitable<import("shiki").MaybeModule<import("shiki").MaybeArray<import("shiki").LanguageRegistration>>>;
+  cfg: () => import("shiki").Awaitable<import("shiki").MaybeModule<import("shiki").MaybeArray<import("shiki").LanguageRegistration>>>;
+  conf: () => import("shiki").Awaitable<import("shiki").MaybeModule<import("shiki").MaybeArray<import("shiki").LanguageRegistration>>>;
+  properties: () => import("shiki").Awaitable<import("shiki").MaybeModule<import("shiki").MaybeArray<import("shiki").LanguageRegistration>>>;
+  toml: () => Promise<typeof import("@shikijs/langs/toml")>;
+};
+/** Theme loaders. Same static-import constraint as {@link LANG_LOADERS}. */
+declare const THEME_LOADERS: {
+  'github-light': () => Promise<typeof import("@shikijs/themes/github-light")>;
+  'github-dark': () => Promise<typeof import("@shikijs/themes/github-dark")>;
+  'github-light-default': () => Promise<typeof import("@shikijs/themes/github-light-default")>;
+  'github-dark-default': () => Promise<typeof import("@shikijs/themes/github-dark-default")>;
+  'vitesse-light': () => Promise<typeof import("@shikijs/themes/vitesse-light")>;
+  'vitesse-dark': () => Promise<typeof import("@shikijs/themes/vitesse-dark")>;
+  'min-light': () => Promise<typeof import("@shikijs/themes/min-light")>;
+  'min-dark': () => Promise<typeof import("@shikijs/themes/min-dark")>;
+  'one-light': () => Promise<typeof import("@shikijs/themes/one-light")>;
+  'one-dark-pro': () => Promise<typeof import("@shikijs/themes/one-dark-pro")>;
+  'catppuccin-latte': () => Promise<typeof import("@shikijs/themes/catppuccin-latte")>;
+  'catppuccin-mocha': () => Promise<typeof import("@shikijs/themes/catppuccin-mocha")>;
+  nord: () => Promise<typeof import("@shikijs/themes/nord")>;
+};
+/** A grammar name accepted by {@link createDocsHighlighter}. */
+type DocsLang = keyof typeof LANG_LOADERS;
+/** A theme name accepted by {@link createDocsHighlighter}. */
+type DocsTheme = keyof typeof THEME_LOADERS;
+/**
+ * The light/dark pair. Two themes rather than one is what makes Shiki emit
+ * `--shiki-light` / `--shiki-dark` CSS variables, which is how the stylesheet
+ * switches colour scheme without shipping a second copy of every token.
+ */
+type DocsThemes = {
+  light: DocsTheme;
+  dark: DocsTheme;
+};
+/**
+ * Languages loaded when none are configured: what technical documentation
+ * actually contains. Anything outside this list falls back to plain text
+ * rather than throwing — see {@link createDocsHighlighter}.
+ */
+declare const DEFAULT_DOCS_LANGS: readonly DocsLang[];
+/** Default theme pair. */
+declare const DEFAULT_DOCS_THEMES: DocsThemes;
+interface DocsHighlighterOptions {
+  /**
+   * Grammars to load. Names or aliases (`'ts'`, `'bash'`). Defaults to
+   * {@link DEFAULT_DOCS_LANGS}.
+   *
+   * Narrowed to {@link DocsLang} so `'typescrpt'` is a compile error rather
+   * than a build-time throw. The runtime check below stays for JavaScript
+   * callers and for values that arrive from JSON config.
+   */
+  langs?: readonly DocsLang[];
+  /** Theme pair. Defaults to {@link DEFAULT_DOCS_THEMES}. */
+  themes?: DocsThemes;
+}
+/**
+ * Create (or reuse) the process-wide highlighter for a given option set.
+ *
+ * Unknown language and theme names throw rather than degrading: the set is
+ * fixed at build time, so a typo in config is a build bug, and silently
+ * shipping unhighlighted code is exactly the failure this package exists to
+ * avoid. If you need a grammar outside the curated set, build your own
+ * `createHighlighterCore` and hand it to `createDocsRenderer({ highlighter })`.
+ */
+declare function createDocsHighlighter(options?: DocsHighlighterOptions): Promise<DocsHighlighter>;
+//#endregion
+export { DEFAULT_DOCS_LANGS, DEFAULT_DOCS_THEMES, DocsHighlighter, DocsHighlighterOptions, DocsLang, DocsTheme, DocsThemes, createDocsHighlighter };

package/dist/highlighter.js

@@ -0,0 +1,183 @@
+import { createHighlighterCore } from "shiki/core";
+import { createJavaScriptRegexEngine } from "shiki/engine/javascript";
+//#region src/highlighter.ts
+/**
+* The syntax highlighter used for documentation code blocks.
+*
+* Deliberately fine-grained: `shiki/core` plus one static import per grammar
+* and per theme. The bundled entry points (`shiki`, `@shikijs/rehype`) pull all
+* 346 grammars — roughly 11MB and four seconds per build worker — for a docs
+* site that realistically uses a dozen. Nothing here reaches the browser
+* either way; the cost is build time, and it is worth avoiding.
+*
+* The regex engine is the JavaScript one, so no WASM is loaded and the module
+* works unchanged in a Next.js build worker or a plain Node script.
+*/
+/**
+* Grammar loaders, keyed by every name an author might reasonably write in a
+* fence. Shiki resolves its own aliases once a grammar is loaded; the extra
+* keys exist so `langs: ['ts']` in user config does not fail the lookup below.
+*
+* Every entry is a static `import()` specifier: that is what lets a bundler
+* see the dependency without pulling the full bundle.
+*/
+/**
+* The `ini` grammar, with `cfg` and `conf` registered as aliases of it.
+*
+* ⚠️ SHIKI RESOLVES A FENCE AGAINST A GRAMMAR'S OWN ALIASES, not against the
+* keys of {@link LANG_LOADERS}. `ini` ships exactly one alias, `properties`, so
+* ```cfg threw `Language 'cfg' not found` and `fallbackLanguage` rendered the
+* block as plain text. Loading the grammar under a `cfg` key would not have
+* helped — the lookup that fails is Shiki's, not ours.
+*
+* It matters because the fence an author types follows the filename. A FiveM
+* docs site is mostly `server.cfg`, and nobody writes ```ini above a file
+* called `server.cfg`.
+*
+* One function object, shared by every key that wants it: the dedup below is by
+* loader identity, so `langs: ['ini', 'cfg']` still loads the grammar once.
+*/
+const loadIni = async () => {
+	const loaded = (await import("@shikijs/langs/ini")).default;
+	return (Array.isArray(loaded) ? loaded : [loaded]).map((grammar) => grammar.name === "ini" ? {
+		...grammar,
+		aliases: [
+			...grammar.aliases ?? [],
+			"cfg",
+			"conf"
+		]
+	} : grammar);
+};
+const LANG_LOADERS = {
+	typescript: () => import("@shikijs/langs/typescript"),
+	ts: () => import("@shikijs/langs/typescript"),
+	tsx: () => import("@shikijs/langs/tsx"),
+	javascript: () => import("@shikijs/langs/javascript"),
+	js: () => import("@shikijs/langs/javascript"),
+	jsx: () => import("@shikijs/langs/jsx"),
+	json: () => import("@shikijs/langs/json"),
+	shellscript: () => import("@shikijs/langs/shellscript"),
+	bash: () => import("@shikijs/langs/shellscript"),
+	sh: () => import("@shikijs/langs/shellscript"),
+	shell: () => import("@shikijs/langs/shellscript"),
+	zsh: () => import("@shikijs/langs/shellscript"),
+	css: () => import("@shikijs/langs/css"),
+	html: () => import("@shikijs/langs/html"),
+	markdown: () => import("@shikijs/langs/markdown"),
+	md: () => import("@shikijs/langs/markdown"),
+	yaml: () => import("@shikijs/langs/yaml"),
+	yml: () => import("@shikijs/langs/yaml"),
+	diff: () => import("@shikijs/langs/diff"),
+	sql: () => import("@shikijs/langs/sql"),
+	python: () => import("@shikijs/langs/python"),
+	py: () => import("@shikijs/langs/python"),
+	go: () => import("@shikijs/langs/go"),
+	rust: () => import("@shikijs/langs/rust"),
+	rs: () => import("@shikijs/langs/rust"),
+	prisma: () => import("@shikijs/langs/prisma"),
+	ini: loadIni,
+	cfg: loadIni,
+	conf: loadIni,
+	properties: loadIni,
+	toml: () => import("@shikijs/langs/toml")
+};
+/** Theme loaders. Same static-import constraint as {@link LANG_LOADERS}. */
+const THEME_LOADERS = {
+	"github-light": () => import("@shikijs/themes/github-light"),
+	"github-dark": () => import("@shikijs/themes/github-dark"),
+	"github-light-default": () => import("@shikijs/themes/github-light-default"),
+	"github-dark-default": () => import("@shikijs/themes/github-dark-default"),
+	"vitesse-light": () => import("@shikijs/themes/vitesse-light"),
+	"vitesse-dark": () => import("@shikijs/themes/vitesse-dark"),
+	"min-light": () => import("@shikijs/themes/min-light"),
+	"min-dark": () => import("@shikijs/themes/min-dark"),
+	"one-light": () => import("@shikijs/themes/one-light"),
+	"one-dark-pro": () => import("@shikijs/themes/one-dark-pro"),
+	"catppuccin-latte": () => import("@shikijs/themes/catppuccin-latte"),
+	"catppuccin-mocha": () => import("@shikijs/themes/catppuccin-mocha"),
+	nord: () => import("@shikijs/themes/nord")
+};
+/**
+* Languages loaded when none are configured: what technical documentation
+* actually contains. Anything outside this list falls back to plain text
+* rather than throwing — see {@link createDocsHighlighter}.
+*/
+const DEFAULT_DOCS_LANGS = [
+	"typescript",
+	"tsx",
+	"javascript",
+	"jsx",
+	"json",
+	"shellscript",
+	"css",
+	"html",
+	"markdown",
+	"yaml",
+	"diff",
+	"sql",
+	"python",
+	"go",
+	"rust",
+	"prisma",
+	"ini",
+	"toml"
+];
+/** Default theme pair. */
+const DEFAULT_DOCS_THEMES = {
+	light: "github-light",
+	dark: "github-dark"
+};
+/**
+* Highlighters are cached per resolved option set, not per call.
+*
+* The *promise* is cached rather than the resolved highlighter because build
+* tools call this concurrently — Next.js renders route segments in parallel —
+* and caching after the await races into two grammar loads. Keyed rather than
+* a single slot so that a second call
+* with different languages gets a highlighter that actually has them.
+*/
+const highlighters = /* @__PURE__ */ new Map();
+function isDocsLang(name) {
+	return Object.hasOwn(LANG_LOADERS, name);
+}
+function isDocsTheme(name) {
+	return Object.hasOwn(THEME_LOADERS, name);
+}
+/**
+* Create (or reuse) the process-wide highlighter for a given option set.
+*
+* Unknown language and theme names throw rather than degrading: the set is
+* fixed at build time, so a typo in config is a build bug, and silently
+* shipping unhighlighted code is exactly the failure this package exists to
+* avoid. If you need a grammar outside the curated set, build your own
+* `createHighlighterCore` and hand it to `createDocsRenderer({ highlighter })`.
+*/
+function createDocsHighlighter(options = {}) {
+	const themes = options.themes ?? DEFAULT_DOCS_THEMES;
+	const requested = options.langs ?? DEFAULT_DOCS_LANGS;
+	for (const theme of [themes.light, themes.dark]) if (!isDocsTheme(theme)) throw new Error(`@waveso/docs: unknown Shiki theme '${theme}'. Supported themes: ${Object.keys(THEME_LOADERS).sort().join(", ")}. To use another theme, pass your own highlighter to createDocsRenderer().`);
+	const langs = [...new Set(requested)].sort();
+	const loaders = /* @__PURE__ */ new Set();
+	for (const lang of langs) {
+		if (!isDocsLang(lang)) throw new Error(`@waveso/docs: unknown code language '${lang}'. Supported languages: ${Object.keys(LANG_LOADERS).sort().join(", ")}. To use another grammar, pass your own highlighter to createDocsRenderer().`);
+		loaders.add(LANG_LOADERS[lang]);
+	}
+	const key = JSON.stringify({
+		langs,
+		themes
+	});
+	const cached = highlighters.get(key);
+	if (cached) return cached;
+	const created = createHighlighterCore({
+		engine: createJavaScriptRegexEngine(),
+		themes: [THEME_LOADERS[themes.light], THEME_LOADERS[themes.dark]],
+		langs: [...loaders]
+	}).catch((error) => {
+		highlighters.delete(key);
+		throw error;
+	});
+	highlighters.set(key, created);
+	return created;
+}
+//#endregion
+export { DEFAULT_DOCS_LANGS, DEFAULT_DOCS_THEMES, createDocsHighlighter };

package/dist/meta.d.ts

@@ -0,0 +1,75 @@
+import { DocNavNode, DocsMeta } from "./types.js";
+import { z } from "zod";
+//#region src/meta.d.ts
+/**
+ * Zod mirror of {@link DocsMeta}.
+ *
+ * Strict on purpose: `meta.json` is hand-written and unvalidated keys are
+ * almost always typos (`page`, `order`, `items`) that would otherwise fail
+ * silently as a sidebar that quietly ignores half the file.
+ */
+declare const docsMetaSchema: z.ZodObject<{
+  title: z.ZodExactOptional<z.ZodString>;
+  pages: z.ZodExactOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+    title: z.ZodString;
+    href: z.ZodString;
+  }, z.core.$strict>]>>>;
+}, z.core.$strict>;
+/**
+ * One child of a directory, as the ordering algorithm sees it.
+ *
+ * Drafts arrive as `hidden` entries rather than being filtered out by the
+ * caller, so that naming a draft in `meta.json` is not a build error that
+ * appears and disappears with `includeDrafts`.
+ */
+interface MetaDirEntry {
+  /** Name as written in `pages`: filename without `.md`, or directory name. */
+  name: string;
+  /** Title used for alphabetical ordering. */
+  title: string;
+  /** Frontmatter `order`, when the page (or a directory's index) sets one. */
+  order?: number;
+  /** The node this entry contributes when it appears in the nav. */
+  node: DocNavNode;
+  /** Directories only: the children `"...name"` splices in at its position. */
+  inlineChildren?: DocNavNode[];
+  /**
+   * Directories only: a link to the directory's own page, spliced in ahead of
+   * {@link MetaDirEntry.inlineChildren}.
+   *
+   * Inline expansion drops the group node, and the group node is the only
+   * carrier of the directory's `href` — without this, `"...api"` publishes
+   * `/docs/api` as a route that no sidebar link reaches.
+   */
+  indexNode?: DocNavNode;
+  /** The directory's own `index.md`: listed only when named explicitly. */
+  isIndex?: boolean;
+  /** Excluded from output, but still resolvable by name (i.e. a draft). */
+  hidden?: boolean;
+}
+/**
+ * Validate a parsed `meta.json`, or throw an error that names the file.
+ */
+declare function parseDocsMeta(raw: unknown, filePath: string): DocsMeta;
+/**
+ * Read and validate `<dirPath>/meta.json`. Resolves to `undefined` when the
+ * file does not exist — most directories do not need one.
+ */
+declare function readDocsMeta(dirPath: string): Promise<DocsMeta | undefined>;
+/**
+ * Order a directory's children into nav nodes.
+ *
+ * With no `pages` list, entries sort by frontmatter `order` ascending and then
+ * by title; entries without an order sort after those with one. With a `pages`
+ * list, entries appear exactly where they are named, and anything unnamed is
+ * dropped unless a `"..."` entry says where to put it.
+ *
+ * @param entries - The directory's children.
+ * @param meta - Its validated `meta.json`, if any.
+ * @param metaPath - Path to that `meta.json`, used in error messages.
+ * @throws When `pages` names a child that does not exist — always a typo, and
+ *   catching it here is the entire reason `meta.json` is validated at build.
+ */
+declare function orderNavEntries(entries: readonly MetaDirEntry[], meta: DocsMeta | undefined, metaPath: string): DocNavNode[];
+//#endregion
+export { MetaDirEntry, docsMetaSchema, orderNavEntries, parseDocsMeta, readDocsMeta };

package/dist/meta.js

@@ -0,0 +1,183 @@
+import { z } from "zod";
+import { readFile } from "node:fs/promises";
+import path from "node:path";
+//#region src/meta.ts
+/**
+* `meta.json` — per-directory ordering, labelling and hand-written nav entries.
+*
+* The ordering algorithm is kept free of filesystem access on purpose: it
+* takes a description of a directory's children ({@link MetaDirEntry}) and
+* returns nav nodes, so it can be tested exhaustively without a fixture tree
+* and reused by anything that can describe a directory.
+*/
+/** A `"---Label---"` separator entry. */
+const SEPARATOR_PATTERN = /^---(.+)---$/;
+/** The rest wildcard: everything not named explicitly, in place. */
+const REST = "...";
+/**
+* `<scheme>:` or protocol-relative `//host` — i.e. a URL that leaves the site.
+* Anything else (`/changelog`, `../pricing`) is internal.
+*/
+const ABSOLUTE_HREF_PATTERN = /^(?:[a-zA-Z][a-zA-Z\d+\-.]*:|\/\/)/;
+/**
+* Zod mirror of {@link DocsMeta}.
+*
+* Strict on purpose: `meta.json` is hand-written and unvalidated keys are
+* almost always typos (`page`, `order`, `items`) that would otherwise fail
+* silently as a sidebar that quietly ignores half the file.
+*/
+const docsMetaSchema = z.strictObject({
+	title: z.string().exactOptional(),
+	pages: z.array(z.union([z.string(), z.strictObject({
+		title: z.string(),
+		href: z.string()
+	})])).exactOptional()
+});
+/**
+* Validate a parsed `meta.json`, or throw an error that names the file.
+*/
+function parseDocsMeta(raw, filePath) {
+	const result = docsMetaSchema.safeParse(raw);
+	if (result.success) return result.data;
+	const details = result.error.issues.map((issue) => `  - ${issue.path.join(".") || "(root)"}: ${issue.message}`).join("\n");
+	throw new Error(`Invalid meta.json at ${filePath}:\n${details}`);
+}
+/**
+* Read and validate `<dirPath>/meta.json`. Resolves to `undefined` when the
+* file does not exist — most directories do not need one.
+*/
+async function readDocsMeta(dirPath) {
+	const filePath = path.join(dirPath, "meta.json");
+	let raw;
+	try {
+		raw = await readFile(filePath, "utf8");
+	} catch (err) {
+		if (isNotFound(err)) return;
+		throw err;
+	}
+	let parsed;
+	try {
+		parsed = JSON.parse(raw);
+	} catch (err) {
+		const reason = err instanceof Error ? err.message : String(err);
+		throw new Error(`Could not parse ${filePath} as JSON: ${reason}`);
+	}
+	return parseDocsMeta(parsed, filePath);
+}
+/**
+* Order a directory's children into nav nodes.
+*
+* With no `pages` list, entries sort by frontmatter `order` ascending and then
+* by title; entries without an order sort after those with one. With a `pages`
+* list, entries appear exactly where they are named, and anything unnamed is
+* dropped unless a `"..."` entry says where to put it.
+*
+* @param entries - The directory's children.
+* @param meta - Its validated `meta.json`, if any.
+* @param metaPath - Path to that `meta.json`, used in error messages.
+* @throws When `pages` names a child that does not exist — always a typo, and
+*   catching it here is the entire reason `meta.json` is validated at build.
+*/
+function orderNavEntries(entries, meta, metaPath) {
+	const pages = meta?.pages;
+	if (pages === void 0) return dropEmptyGroups(sortEntries(entries.filter((entry) => isListedByDefault(entry))).map((entry) => entry.node));
+	const byName = indexByName(entries, metaPath);
+	const used = /* @__PURE__ */ new Set();
+	const nodes = [];
+	let restAt = -1;
+	for (const page of pages) {
+		if (typeof page !== "string") {
+			nodes.push({
+				type: "link",
+				title: page.title,
+				href: page.href,
+				external: ABSOLUTE_HREF_PATTERN.test(page.href)
+			});
+			continue;
+		}
+		const separator = SEPARATOR_PATTERN.exec(page);
+		if (separator) {
+			nodes.push({
+				type: "separator",
+				title: (separator[1] ?? "").trim()
+			});
+			continue;
+		}
+		if (page === REST) {
+			if (restAt !== -1) throw new Error(`${metaPath} has more than one "..." entry. A directory has a single set of unnamed pages, so only one wildcard can be honoured — remove the extra.`);
+			restAt = nodes.length;
+			continue;
+		}
+		if (page.startsWith(REST)) {
+			const name = page.slice(3);
+			const target = byName.get(name);
+			if (!target?.inlineChildren) throw new Error(`${metaPath} entry "${page}" expands a directory named "${name}", which is not a subdirectory here. ${describeAvailable(entries, true)}`);
+			used.add(name);
+			if (target.indexNode !== void 0) nodes.push(target.indexNode);
+			nodes.push(...target.inlineChildren);
+			continue;
+		}
+		const target = byName.get(page);
+		if (!target) throw new Error(`${metaPath} lists "${page}", which does not exist. ${describeAvailable(entries, false)}`);
+		used.add(page);
+		if (!target.hidden) nodes.push(target.node);
+	}
+	if (restAt !== -1) {
+		const rest = sortEntries(entries.filter((entry) => isListedByDefault(entry) && !used.has(entry.name))).map((entry) => entry.node);
+		nodes.splice(restAt, 0, ...rest);
+	}
+	return dropEmptyGroups(nodes);
+}
+/**
+* Index the directory's children by the name `pages` addresses them with.
+*
+* A plain `new Map(entries.map(…))` is last-wins, which turns an ambiguous
+* name into a page that silently disappears from the sidebar while remaining a
+* published route. The source layer merges the one ambiguity that has a sane
+* reading — `guides.md` beside a `guides/` with no `index.md` — so anything
+* still colliding here is a name no `meta.json` entry could address.
+*/
+function indexByName(entries, metaPath) {
+	const byName = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const clash = byName.get(entry.name);
+		if (clash !== void 0) throw new Error(`${metaPath} cannot address "${entry.name}": ${describeEntry(clash)} and ${describeEntry(entry)} both claim that name. Rename one.`);
+		byName.set(entry.name, entry);
+	}
+	return byName;
+}
+function describeEntry(entry) {
+	return entry.inlineChildren === void 0 ? `${entry.name}.md` : `${entry.name}/`;
+}
+/**
+* Groups that turned out to hold nothing (every page a draft, or none of them
+* named in a child `meta.json`) are dropped here rather than earlier so that
+* naming such a directory in `meta.json` never fails the build.
+*/
+function dropEmptyGroups(nodes) {
+	return nodes.filter((node) => node.type !== "group" || node.children.length > 0 || node.href !== void 0);
+}
+/** An entry appears without being named: not the index, not a draft. */
+function isListedByDefault(entry) {
+	return entry.isIndex !== true && entry.hidden !== true;
+}
+function sortEntries(entries) {
+	return [...entries].sort(compareEntries);
+}
+function compareEntries(a, b) {
+	if (a.order !== void 0 && b.order !== void 0) {
+		if (a.order !== b.order) return a.order - b.order;
+	} else if (a.order !== void 0) return -1;
+	else if (b.order !== void 0) return 1;
+	return a.title.localeCompare(b.title, "en");
+}
+function describeAvailable(entries, directoriesOnly) {
+	const names = entries.filter((entry) => !directoriesOnly || entry.inlineChildren !== void 0).map((entry) => entry.name).sort();
+	const label = directoriesOnly ? "Subdirectories" : "Available entries";
+	return names.length === 0 ? `${label}: (none).` : `${label}: ${names.join(", ")}.`;
+}
+function isNotFound(err) {
+	return typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT";
+}
+//#endregion
+export { docsMetaSchema, orderNavEntries, parseDocsMeta, readDocsMeta };