@optique/man 1.4.0-dev.2899 → 1.4.0-dev.2935

package/README.md

@@ -98,6 +98,23 @@ const manPage = generateManPage(parser, {
 ~~~~
 
 
+Markdown command references
+---------------------------
+
+Import `formatCommandReference()` from `@optique/man/markdown` for one linked
+reference containing explicitly supplied command pages. Supported built-in
+definitions can supply pages through `collectDocPages()` from
+`@optique/core/doc-pages`, with strict reporting for unsupported scopes. Neither
+subpath is imported by ordinary parser or runner entry points.
+
+See the [Markdown reference guide] and the [runnable example]. Coverage is
+author-declared, including whether runner-added help/version/completion forms
+are documented.
+
+[Markdown reference guide]: https://optique.dev/concepts/markdown-reference
+[runnable example]: https://github.com/dahlia/optique/tree/main/packages/man/test/fixtures/markdown-reference
+
+
 Documentation
 -------------
 

package/dist/chunk-CUT6urMc.cjs

@@ -0,0 +1,30 @@
+//#region rolldown:runtime
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+
+//#endregion
+
+Object.defineProperty(exports, '__toESM', {
+  enumerable: true,
+  get: function () {
+    return __toESM;
+  }
+});

package/dist/cli.cjs

@@ -1,29 +1,31 @@
 #!/usr/bin/env node
-const require_man = require('./man-Dp2YQIdn.cjs');
+const require_chunk = require('./chunk-CUT6urMc.cjs');
 require('./roff-C8MvQ2tL.cjs');
-const require_generator = require('./generator-OV4-0NLg.cjs');
-const __optique_core_constructs = require_man.__toESM(require("@optique/core/constructs"));
-const __optique_core_primitives = require_man.__toESM(require("@optique/core/primitives"));
-const __optique_core_valueparser = require_man.__toESM(require("@optique/core/valueparser"));
-const __optique_core_modifiers = require_man.__toESM(require("@optique/core/modifiers"));
-const __optique_core_message = require_man.__toESM(require("@optique/core/message"));
-const __optique_core_program = require_man.__toESM(require("@optique/core/program"));
-const __optique_run = require_man.__toESM(require("@optique/run"));
-const node_fs = require_man.__toESM(require("node:fs"));
-const node_fs_promises = require_man.__toESM(require("node:fs/promises"));
-const node_path = require_man.__toESM(require("node:path"));
-const node_process = require_man.__toESM(require("node:process"));
-const node_url = require_man.__toESM(require("node:url"));
+require('./man-ChbwsIhG.cjs');
+const require_generator = require('./generator-DYAqAqpo.cjs');
+const __optique_core_constructs = require_chunk.__toESM(require("@optique/core/constructs"));
+const __optique_core_primitives = require_chunk.__toESM(require("@optique/core/primitives"));
+const __optique_core_valueparser = require_chunk.__toESM(require("@optique/core/valueparser"));
+const __optique_core_modifiers = require_chunk.__toESM(require("@optique/core/modifiers"));
+const __optique_core_message = require_chunk.__toESM(require("@optique/core/message"));
+const __optique_core_program = require_chunk.__toESM(require("@optique/core/program"));
+const __optique_run = require_chunk.__toESM(require("@optique/run"));
+const node_fs = require_chunk.__toESM(require("node:fs"));
+const node_fs_promises = require_chunk.__toESM(require("node:fs/promises"));
+const node_path = require_chunk.__toESM(require("node:path"));
+const node_process = require_chunk.__toESM(require("node:process"));
+const node_url = require_chunk.__toESM(require("node:url"));
 
 //#region deno.json
 var name = "@optique/man";
-var version = "1.4.0-dev.2899+9c2973b0";
+var version = "1.4.0-dev.2935+fc126fd1";
 var license = "MIT";
 var exports$1 = {
 	".": "./src/index.ts",
 	"./roff": "./src/roff.ts",
 	"./man": "./src/man.ts",
-	"./cli": "./src/cli.ts"
+	"./cli": "./src/cli.ts",
+	"./markdown": "./src/markdown.ts"
 };
 var imports = {
 	"#src/": "./src/",
@@ -47,6 +49,7 @@ var tasks = {
 		"test:bun"
 	] }
 };
+var publish = { "exclude": ["test/prototypes/", "test/fixtures/markdown-reference/"] };
 var deno_default = {
 	name,
 	version,
@@ -54,7 +57,8 @@ var deno_default = {
 	exports: exports$1,
 	imports,
 	exclude,
-	tasks
+	tasks,
+	publish
 };
 
 //#endregion

package/dist/cli.js

@@ -17,13 +17,14 @@ import { fileURLToPath, pathToFileURL } from "node:url";
 
 //#region deno.json
 var name = "@optique/man";
-var version = "1.4.0-dev.2899+9c2973b0";
+var version = "1.4.0-dev.2935+fc126fd1";
 var license = "MIT";
 var exports = {
 	".": "./src/index.ts",
 	"./roff": "./src/roff.ts",
 	"./man": "./src/man.ts",
-	"./cli": "./src/cli.ts"
+	"./cli": "./src/cli.ts",
+	"./markdown": "./src/markdown.ts"
 };
 var imports = {
 	"#src/": "./src/",
@@ -47,6 +48,7 @@ var tasks = {
 		"test:bun"
 	] }
 };
+var publish = { "exclude": ["test/prototypes/", "test/fixtures/markdown-reference/"] };
 var deno_default = {
 	name,
 	version,
@@ -54,7 +56,8 @@ var deno_default = {
 	exports,
 	imports,
 	exclude,
-	tasks
+	tasks,
+	publish
 };
 
 //#endregion

package/dist/{generator-OV4-0NLg.cjs → generator-DYAqAqpo.cjs}

@@ -1,5 +1,6 @@
-const require_man = require('./man-Dp2YQIdn.cjs');
-const __optique_core_parser = require_man.__toESM(require("@optique/core/parser"));
+const require_chunk = require('./chunk-CUT6urMc.cjs');
+const require_man = require('./man-ChbwsIhG.cjs');
+const __optique_core_parser = require_chunk.__toESM(require("@optique/core/parser"));
 
 //#region src/generator.ts
 /**

package/dist/generator.cjs

@@ -1,6 +1,6 @@
-require('./man-Dp2YQIdn.cjs');
 require('./roff-C8MvQ2tL.cjs');
-const require_generator = require('./generator-OV4-0NLg.cjs');
+require('./man-ChbwsIhG.cjs');
+const require_generator = require('./generator-DYAqAqpo.cjs');
 
 exports.generateManPage = require_generator.generateManPage;
 exports.generateManPageAsync = require_generator.generateManPageAsync;

package/dist/index.cjs

@@ -1,6 +1,6 @@
-const require_man = require('./man-Dp2YQIdn.cjs');
 const require_roff = require('./roff-C8MvQ2tL.cjs');
-const require_generator = require('./generator-OV4-0NLg.cjs');
+const require_man = require('./man-ChbwsIhG.cjs');
+const require_generator = require('./generator-DYAqAqpo.cjs');
 
 exports.escapeHyphens = require_roff.escapeHyphens;
 exports.escapeQuotedValue = require_roff.escapeQuotedValue;

package/dist/{man-Dp2YQIdn.cjs → man-ChbwsIhG.cjs}

@@ -1,30 +1,8 @@
-//#region rolldown:runtime
-var __create = Object.create;
-var __defProp = Object.defineProperty;
-var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
-var __getOwnPropNames = Object.getOwnPropertyNames;
-var __getProtoOf = Object.getPrototypeOf;
-var __hasOwnProp = Object.prototype.hasOwnProperty;
-var __copyProps = (to, from, except, desc) => {
-	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
-		key = keys[i];
-		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
-			get: ((k) => from[k]).bind(null, key),
-			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
-		});
-	}
-	return to;
-};
-var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
-	value: mod,
-	enumerable: true
-}) : target, mod));
-
-//#endregion
+const require_chunk = require('./chunk-CUT6urMc.cjs');
 const require_roff = require('./roff-C8MvQ2tL.cjs');
-const __optique_core_doc = __toESM(require("@optique/core/doc"));
-const __optique_core_usage = __toESM(require("@optique/core/usage"));
-const __optique_core_internal_usage = __toESM(require("@optique/core/internal/usage"));
+const __optique_core_doc = require_chunk.__toESM(require("@optique/core/doc"));
+const __optique_core_usage = require_chunk.__toESM(require("@optique/core/usage"));
+const __optique_core_internal_usage = require_chunk.__toESM(require("@optique/core/internal/usage"));
 
 //#region src/man.ts
 /**
@@ -449,12 +427,6 @@ function formatDocPageAsMan(page, options) {
 }
 
 //#endregion
-Object.defineProperty(exports, '__toESM', {
-  enumerable: true,
-  get: function () {
-    return __toESM;
-  }
-});
 Object.defineProperty(exports, 'formatDateForMan', {
   enumerable: true,
   get: function () {

package/dist/man.cjs

@@ -1,5 +1,5 @@
-const require_man = require('./man-Dp2YQIdn.cjs');
 require('./roff-C8MvQ2tL.cjs');
+const require_man = require('./man-ChbwsIhG.cjs');
 
 exports.formatDateForMan = require_man.formatDateForMan;
 exports.formatDocPageAsMan = require_man.formatDocPageAsMan;

package/dist/markdown.cjs

@@ -0,0 +1,248 @@
+const require_chunk = require('./chunk-CUT6urMc.cjs');
+const __optique_core_usage = require_chunk.__toESM(require("@optique/core/usage"));
+
+//#region src/markdown.ts
+function validateToken(token) {
+	if (typeof token !== "string" || token.length === 0 || /[\s\x00-\x1f\x7f-\x9f]/u.test(token) || !token.isWellFormed()) throw new TypeError("Command paths and aliases must contain nonempty tokens without whitespace or control characters.");
+}
+function pathKey(path) {
+	for (const token of path) validateToken(token);
+	return JSON.stringify(path);
+}
+/**
+* Returns an injective anchor from the UTF-8 bytes of a JSON canonical path.
+* The dot separates these IDs from GitHub/VitePress heading slugs.
+* @param path Canonical command tokens; an empty array identifies root.
+* @returns The explicit anchor ID, without a leading hash.
+* @throws {TypeError} If a token is empty, ill-formed, or contains whitespace
+* or control characters.
+* @since 1.4.0
+*/
+function getCommandReferenceAnchor(path) {
+	const bytes = new TextEncoder().encode(pathKey(path));
+	return "optique-command." + Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function singleLine(input) {
+	return input.replace(/[\r\n\t]/g, " ").replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+function code(input) {
+	const content = singleLine(input);
+	if (content === "") return "<code></code>";
+	const fence = "`".repeat(Math.max(0, ...Array.from(content.matchAll(/`+/g), (match) => match[0].length)) + 1);
+	const padding = content.startsWith("`") || content.endsWith("`") || /^ .* $/u.test(content) ? " " : "";
+	return fence + padding + content + padding + fence;
+}
+function prose(input) {
+	return input.replace(/\r\n?/g, "\n").split("\n").map((line) => {
+		const escaped = singleLine(line).replace(/[!"#$%&'()*+,\-./:;<=>?@[\\\]^_`{|}~]/g, (char) => {
+			if (char === "&") return "&amp;";
+			if (char === "<") return "&lt;";
+			if (char === ">") return "&gt;";
+			return "\\" + char;
+		});
+		return escaped.replace(/^ +/, (spaces) => "&#32;".repeat(spaces.length));
+	}).join("\\\n");
+}
+function formatMessageTerm(term) {
+	switch (term.type) {
+		case "text": return prose(term.text);
+		case "optionName": return code(term.optionName);
+		case "optionNames": return term.optionNames.map(code).join(", ");
+		case "metavar": return code(term.metavar);
+		case "value": return code(term.value);
+		case "values": return term.values.map(code).join(" ");
+		case "envVar": return code(term.envVar);
+		case "commandLine": return code(term.commandLine);
+		case "url": return code(term.url.href);
+		case "lineBreak": return "\\\n";
+	}
+}
+function formatMessage(message) {
+	let previousCode = false;
+	return message.map((term) => {
+		const content = formatMessageTerm(term);
+		const semanticCode = term.type !== "text" && term.type !== "lineBreak";
+		const separator = previousCode && semanticCode && content !== "" ? "<!-- -->" : "";
+		if (content !== "") previousCode = semanticCode;
+		return separator + content;
+	}).join("").replace(/(?:\\\n)+$/, "");
+}
+function link(label, path) {
+	return `<a href="#${getCommandReferenceAnchor(path)}"><code>${prose(singleLine(label))}</code></a>`;
+}
+function visibleAliases(entry) {
+	const hidden = new Set(entry.hiddenAliases);
+	return [...new Set(entry.aliases)].filter((alias) => !hidden.has(alias) && alias !== entry.path.at(-1));
+}
+function hiddenInTree(entry, index) {
+	for (let length = 1; length <= entry.path.length; length++) if ((0, __optique_core_usage.isDocHidden)(index.get(pathKey(entry.path.slice(0, length)))?.hidden)) return true;
+	return false;
+}
+function validateEntries(entries) {
+	const index = /* @__PURE__ */ new Map();
+	const spellings = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const key = pathKey(entry.path);
+		if (index.has(key)) throw new TypeError(`Duplicate command path: ${key}`);
+		index.set(key, entry);
+		for (const alias of [...entry.aliases ?? [], ...entry.hiddenAliases ?? []]) validateToken(alias);
+		if (entry.path.length === 0) {
+			if (entry.aliases?.length || entry.hiddenAliases?.length || entry.hidden) throw new TypeError("The root page cannot have aliases or hidden visibility.");
+			continue;
+		}
+		for (const name of [
+			entry.path.at(-1),
+			...entry.aliases ?? [],
+			...entry.hiddenAliases ?? []
+		]) {
+			const spelling = pathKey([...entry.path.slice(0, -1), name]);
+			const destination = spellings.get(spelling);
+			if (destination != null && destination !== key) throw new TypeError(`Ambiguous command spelling: ${spelling}`);
+			spellings.set(spelling, key);
+		}
+	}
+	return index;
+}
+function commandTarget(entry, parent, index) {
+	return entry.term.type === "command" ? index.get(pathKey([...parent.path, entry.term.name])) : void 0;
+}
+function entryHidden(entry) {
+	return "hidden" in entry.term && (0, __optique_core_usage.isDocHidden)(entry.term.hidden);
+}
+function validateCoverage(coverage) {
+	if (coverage == null || !["all-visible", "partial"].includes(coverage.commands) || [
+		coverage.help,
+		coverage.version,
+		coverage.completion
+	].some((value) => value !== "included" && value !== "excluded")) throw new TypeError("Reference coverage must declare commands and runner-added help, version, and completion inputs.");
+}
+/**
+* Renders supplied command pages in caller order as one Markdown reference.
+*
+* Coverage is always author-declared. Visible child references and canonical
+* prefixes are checked, but commands absent from every supplied page cannot be
+* discovered. The renderer never collects pages or evaluates parser callbacks.
+* Messages are documentation text rather than Markdown. Generated anchors and
+* internal links require raw HTML support; bare web/email text may be linkified
+* by a consumer. Every page's usage already includes its command tokens.
+*
+* @param entries Canonical command pages, with explicit aliases and visibility.
+* @param options Program metadata, coverage declaration and presentation policy.
+* @returns A deterministic Markdown document ending in one newline.
+* @throws {TypeError} If paths/aliases are invalid or ambiguous, a canonical
+* path is duplicated, metadata is invalid, or declared complete coverage has
+* missing visible command pages.
+* @since 1.4.0
+*/
+function formatCommandReference(entries, options) {
+	(0, __optique_core_usage.formatUsage)(options.name, [], { colors: false });
+	validateCoverage(options.coverage);
+	const index = validateEntries(entries);
+	const visible = entries.filter((entry) => !hiddenInTree(entry, index));
+	const unresolved = options.unresolved?.filter((gap) => !hiddenInTree({
+		path: gap.path,
+		page: { sections: [] }
+	}, index)) ?? [];
+	for (const gap of unresolved) {
+		pathKey(gap.path);
+		if (gap.scope !== "page" && gap.scope !== "subtree") throw new TypeError("An unresolved scope must be page or subtree.");
+	}
+	if (unresolved.length > 0 && options.coverage.commands === "all-visible") throw new TypeError("Unresolved command documentation requires partial coverage.");
+	const missing = /* @__PURE__ */ new Map();
+	if (!index.has("[]")) missing.set("[]", []);
+	for (const entry of visible) {
+		for (let length = 0; length < entry.path.length; length++) {
+			const prefix = entry.path.slice(0, length);
+			if (!index.has(pathKey(prefix))) missing.set(pathKey(prefix), prefix);
+		}
+		for (const section of entry.page.sections) for (const item of section.entries) {
+			if (entryHidden(item) || item.term.type !== "command") continue;
+			const target = commandTarget(item, entry, index);
+			if (target == null) {
+				const path = [...entry.path, item.term.name];
+				missing.set(pathKey(path), path);
+			}
+		}
+	}
+	if (missing.size > 0 && options.coverage.commands === "all-visible") throw new TypeError(`Missing command pages: ${[...missing.values()].map((path) => JSON.stringify(path)).join(", ")}`);
+	const output = [`# ${code(options.name)} command reference`];
+	const addMessage = (content) => {
+		if (content != null && content.length > 0) output.push(formatMessage(content));
+	};
+	if (options.version != null) output.push(`Version: ${code(options.version)}`);
+	addMessage(options.brief);
+	addMessage(options.description);
+	output.push(`Coverage: author-declared ${options.coverage.commands === "all-visible" ? "all visible commands" : "partial command reference"}.`);
+	output.push("Runner inputs: " + [
+		"help",
+		"version",
+		"completion"
+	].map((feature) => `${feature}: ${options.coverage[feature] === "included" ? "included" : "not documented here (if configured)"}`).join("; ") + ".");
+	if (missing.size > 0) output.push("Missing command pages: " + [...missing.values()].map((path) => code([options.name, ...path].join(" "))).join(", ") + ".");
+	if (unresolved.length > 0) output.push("## Unresolved documentation", unresolved.map((gap) => ` -  ${code([options.name, ...gap.path].join(" "))} (${gap.scope}): ${code(gap.reason)}`).join("\n"));
+	output.push("## Contents");
+	output.push(visible.map((entry) => {
+		const fullName = [options.name, ...entry.path].join(" ");
+		const aliases = entry.showAliases ?? options.showAliases ?? false ? visibleAliases(entry).map((alias) => link([
+			options.name,
+			...entry.path.slice(0, -1),
+			alias
+		].join(" "), entry.path)) : [];
+		return ` -  ${link(fullName, entry.path)}${aliases.length > 0 ? ` (aliases: ${aliases.join(", ")})` : ""}`;
+	}).join("\n"));
+	for (const entry of visible) {
+		const page = entry.page;
+		output.push(`<a id="${getCommandReferenceAnchor(entry.path)}"></a>`);
+		output.push(`## ${code([options.name, ...entry.path].join(" "))}`);
+		addMessage(page.brief);
+		if ((options.showUsage ?? page.showUsage ?? true) && page.usage != null) {
+			const usage = (0, __optique_core_usage.formatUsage)(options.name, page.usage, { colors: false }).replace(/\r\n?/g, "\n").split("\n").map(singleLine).join("\n");
+			const fence = "~".repeat(Math.max(3, ...Array.from(usage.matchAll(/~+/g), (match) => match[0].length + 1)));
+			output.push("### Usage", `${fence} text\n${usage}\n${fence}`);
+		}
+		addMessage(page.description);
+		for (const section of page.sections) {
+			const items = [];
+			for (const item of section.entries) {
+				if (entryHidden(item)) continue;
+				const target = commandTarget(item, entry, index);
+				if (target != null && hiddenInTree(target, index)) continue;
+				const label = (0, __optique_core_usage.formatUsageTerm)(item.term, {
+					context: "doc",
+					colors: false
+				});
+				if (label === "") continue;
+				const aliases = target != null && (item.showAliases ?? target.showAliases ?? options.showAliases ?? false) ? visibleAliases(target).map((alias) => link(alias, target.path)) : [];
+				let content = " -  " + (target == null ? code(label) : link(label, target.path));
+				if (aliases.length > 0) content += ` (aliases: ${aliases.join(", ")})`;
+				const details = [];
+				if (item.description != null) details.push(formatMessage(item.description));
+				if (item.default != null) details.push("Default: " + formatMessage(item.default));
+				if (item.choices != null) details.push("Choices: " + formatMessage(item.choices));
+				if (item.envVars?.length) details.push("Environment: " + item.envVars.map(code).join(", "));
+				if (details.length > 0) content += "\n\n" + details.join("\n\n").split("\n").map((line) => "    " + line).join("\n");
+				items.push(content);
+			}
+			if (items.length > 0) output.push("### " + prose(singleLine(section.title ?? "Inputs")), items.join("\n\n"));
+		}
+		const bindings = page.environmentBindings?.filter((binding) => !(0, __optique_core_usage.isDocHidden)(binding.hidden));
+		if (bindings?.length) output.push("### Environment", bindings.map((binding) => ` -  ${code(binding.name)}${binding.description == null ? "" : ": " + formatMessage(binding.description).replaceAll("\n", "\n    ")}`).join("\n"));
+		for (const [title, content] of [
+			["Examples", page.examples],
+			["Author", page.author],
+			["Bugs", page.bugs],
+			["Notes", page.footer]
+		]) if (content != null && content.length > 0) output.push(`### ${title}`, formatMessage(content));
+	}
+	for (const [title, content] of [
+		["Examples", options.examples],
+		["Author", options.author],
+		["Bugs", options.bugs],
+		["Notes", options.footer]
+	]) if (content != null && content.length > 0) output.push(`## ${title}`, formatMessage(content));
+	return output.filter((part) => part !== "").join("\n\n") + "\n";
+}
+
+//#endregion
+exports.formatCommandReference = formatCommandReference;
+exports.getCommandReferenceAnchor = getCommandReferenceAnchor;

package/dist/markdown.d.cts

@@ -0,0 +1,81 @@
+import { ProgramMetadata } from "@optique/core/program";
+import { DocPage } from "@optique/core/doc";
+import { HiddenVisibility } from "@optique/core/usage";
+
+//#region src/markdown.d.ts
+
+/** A supplied page and its canonical identity. @since 1.4.0 */
+interface MarkdownCommandEntry {
+  /** Canonical command tokens, excluding the program name. Empty for root. */
+  readonly path: readonly string[];
+  /** Already constructed documentation; usage includes command tokens. */
+  readonly page: DocPage;
+  /** Visible alternative names of this command under its canonical parent. */
+  readonly aliases?: readonly string[];
+  /** Accepted names that must never be displayed. */
+  readonly hiddenAliases?: readonly string[];
+  /** Documentation-hidden parents suppress every supplied descendant. */
+  readonly hidden?: HiddenVisibility;
+  /** Alias display override for this command's contents entry. */
+  readonly showAliases?: boolean;
+}
+/** Author assertions about the supplied reference's scope. @since 1.4.0 */
+interface MarkdownReferenceCoverage {
+  /** Whether the author has supplied every visible command in this scope. */
+  readonly commands: "all-visible" | "partial";
+  /** Whether all configured help forms in this scope are documented. */
+  readonly help: "included" | "excluded";
+  /** Whether all configured version forms in this scope are documented. */
+  readonly version: "included" | "excluded";
+  /** Whether all configured completion forms in this scope are documented. */
+  readonly completion: "included" | "excluded";
+}
+/** Program metadata and presentation options for a reference. @since 1.4.0 */
+interface MarkdownReferenceOptions extends ProgramMetadata {
+  /** Required author declaration, printed in the artifact. */
+  readonly coverage: MarkdownReferenceCoverage;
+  /** Default alias display, overridden by command entries and DocEntries. */
+  readonly showAliases?: boolean;
+  /** Override each supplied page's showUsage setting. Defaults to that page. */
+  readonly showUsage?: boolean;
+  /** Collection omissions to print in a partial reference. Hidden scopes skip them. */
+  readonly unresolved?: readonly {
+    /** Visible enclosing canonical path. */
+    readonly path: readonly string[];
+    /** Whether the gap affects one page or an opaque subtree. */
+    readonly scope: "page" | "subtree";
+    /** Documentation-only diagnostic, rendered as text. */
+    readonly reason: string;
+  }[];
+}
+/**
+ * Returns an injective anchor from the UTF-8 bytes of a JSON canonical path.
+ * The dot separates these IDs from GitHub/VitePress heading slugs.
+ * @param path Canonical command tokens; an empty array identifies root.
+ * @returns The explicit anchor ID, without a leading hash.
+ * @throws {TypeError} If a token is empty, ill-formed, or contains whitespace
+ * or control characters.
+ * @since 1.4.0
+ */
+declare function getCommandReferenceAnchor(path: readonly string[]): string;
+/**
+ * Renders supplied command pages in caller order as one Markdown reference.
+ *
+ * Coverage is always author-declared. Visible child references and canonical
+ * prefixes are checked, but commands absent from every supplied page cannot be
+ * discovered. The renderer never collects pages or evaluates parser callbacks.
+ * Messages are documentation text rather than Markdown. Generated anchors and
+ * internal links require raw HTML support; bare web/email text may be linkified
+ * by a consumer. Every page's usage already includes its command tokens.
+ *
+ * @param entries Canonical command pages, with explicit aliases and visibility.
+ * @param options Program metadata, coverage declaration and presentation policy.
+ * @returns A deterministic Markdown document ending in one newline.
+ * @throws {TypeError} If paths/aliases are invalid or ambiguous, a canonical
+ * path is duplicated, metadata is invalid, or declared complete coverage has
+ * missing visible command pages.
+ * @since 1.4.0
+ */
+declare function formatCommandReference(entries: readonly MarkdownCommandEntry[], options: MarkdownReferenceOptions): string;
+//#endregion
+export { MarkdownCommandEntry, MarkdownReferenceCoverage, MarkdownReferenceOptions, formatCommandReference, getCommandReferenceAnchor };

package/dist/markdown.d.ts

@@ -0,0 +1,81 @@
+import { ProgramMetadata } from "@optique/core/program";
+import { DocPage } from "@optique/core/doc";
+import { HiddenVisibility } from "@optique/core/usage";
+
+//#region src/markdown.d.ts
+
+/** A supplied page and its canonical identity. @since 1.4.0 */
+interface MarkdownCommandEntry {
+  /** Canonical command tokens, excluding the program name. Empty for root. */
+  readonly path: readonly string[];
+  /** Already constructed documentation; usage includes command tokens. */
+  readonly page: DocPage;
+  /** Visible alternative names of this command under its canonical parent. */
+  readonly aliases?: readonly string[];
+  /** Accepted names that must never be displayed. */
+  readonly hiddenAliases?: readonly string[];
+  /** Documentation-hidden parents suppress every supplied descendant. */
+  readonly hidden?: HiddenVisibility;
+  /** Alias display override for this command's contents entry. */
+  readonly showAliases?: boolean;
+}
+/** Author assertions about the supplied reference's scope. @since 1.4.0 */
+interface MarkdownReferenceCoverage {
+  /** Whether the author has supplied every visible command in this scope. */
+  readonly commands: "all-visible" | "partial";
+  /** Whether all configured help forms in this scope are documented. */
+  readonly help: "included" | "excluded";
+  /** Whether all configured version forms in this scope are documented. */
+  readonly version: "included" | "excluded";
+  /** Whether all configured completion forms in this scope are documented. */
+  readonly completion: "included" | "excluded";
+}
+/** Program metadata and presentation options for a reference. @since 1.4.0 */
+interface MarkdownReferenceOptions extends ProgramMetadata {
+  /** Required author declaration, printed in the artifact. */
+  readonly coverage: MarkdownReferenceCoverage;
+  /** Default alias display, overridden by command entries and DocEntries. */
+  readonly showAliases?: boolean;
+  /** Override each supplied page's showUsage setting. Defaults to that page. */
+  readonly showUsage?: boolean;
+  /** Collection omissions to print in a partial reference. Hidden scopes skip them. */
+  readonly unresolved?: readonly {
+    /** Visible enclosing canonical path. */
+    readonly path: readonly string[];
+    /** Whether the gap affects one page or an opaque subtree. */
+    readonly scope: "page" | "subtree";
+    /** Documentation-only diagnostic, rendered as text. */
+    readonly reason: string;
+  }[];
+}
+/**
+ * Returns an injective anchor from the UTF-8 bytes of a JSON canonical path.
+ * The dot separates these IDs from GitHub/VitePress heading slugs.
+ * @param path Canonical command tokens; an empty array identifies root.
+ * @returns The explicit anchor ID, without a leading hash.
+ * @throws {TypeError} If a token is empty, ill-formed, or contains whitespace
+ * or control characters.
+ * @since 1.4.0
+ */
+declare function getCommandReferenceAnchor(path: readonly string[]): string;
+/**
+ * Renders supplied command pages in caller order as one Markdown reference.
+ *
+ * Coverage is always author-declared. Visible child references and canonical
+ * prefixes are checked, but commands absent from every supplied page cannot be
+ * discovered. The renderer never collects pages or evaluates parser callbacks.
+ * Messages are documentation text rather than Markdown. Generated anchors and
+ * internal links require raw HTML support; bare web/email text may be linkified
+ * by a consumer. Every page's usage already includes its command tokens.
+ *
+ * @param entries Canonical command pages, with explicit aliases and visibility.
+ * @param options Program metadata, coverage declaration and presentation policy.
+ * @returns A deterministic Markdown document ending in one newline.
+ * @throws {TypeError} If paths/aliases are invalid or ambiguous, a canonical
+ * path is duplicated, metadata is invalid, or declared complete coverage has
+ * missing visible command pages.
+ * @since 1.4.0
+ */
+declare function formatCommandReference(entries: readonly MarkdownCommandEntry[], options: MarkdownReferenceOptions): string;
+//#endregion
+export { MarkdownCommandEntry, MarkdownReferenceCoverage, MarkdownReferenceOptions, formatCommandReference, getCommandReferenceAnchor };

package/dist/markdown.js

@@ -0,0 +1,246 @@
+import { formatUsage, formatUsageTerm, isDocHidden } from "@optique/core/usage";
+
+//#region src/markdown.ts
+function validateToken(token) {
+	if (typeof token !== "string" || token.length === 0 || /[\s\x00-\x1f\x7f-\x9f]/u.test(token) || !token.isWellFormed()) throw new TypeError("Command paths and aliases must contain nonempty tokens without whitespace or control characters.");
+}
+function pathKey(path) {
+	for (const token of path) validateToken(token);
+	return JSON.stringify(path);
+}
+/**
+* Returns an injective anchor from the UTF-8 bytes of a JSON canonical path.
+* The dot separates these IDs from GitHub/VitePress heading slugs.
+* @param path Canonical command tokens; an empty array identifies root.
+* @returns The explicit anchor ID, without a leading hash.
+* @throws {TypeError} If a token is empty, ill-formed, or contains whitespace
+* or control characters.
+* @since 1.4.0
+*/
+function getCommandReferenceAnchor(path) {
+	const bytes = new TextEncoder().encode(pathKey(path));
+	return "optique-command." + Array.from(bytes, (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+function singleLine(input) {
+	return input.replace(/[\r\n\t]/g, " ").replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f-\x9f]/g, (char) => `\\u${char.charCodeAt(0).toString(16).padStart(4, "0")}`);
+}
+function code(input) {
+	const content = singleLine(input);
+	if (content === "") return "<code></code>";
+	const fence = "`".repeat(Math.max(0, ...Array.from(content.matchAll(/`+/g), (match) => match[0].length)) + 1);
+	const padding = content.startsWith("`") || content.endsWith("`") || /^ .* $/u.test(content) ? " " : "";
+	return fence + padding + content + padding + fence;
+}
+function prose(input) {
+	return input.replace(/\r\n?/g, "\n").split("\n").map((line) => {
+		const escaped = singleLine(line).replace(/[!"#$%&'()*+,\-./:;<=>?@[\\\]^_`{|}~]/g, (char) => {
+			if (char === "&") return "&amp;";
+			if (char === "<") return "&lt;";
+			if (char === ">") return "&gt;";
+			return "\\" + char;
+		});
+		return escaped.replace(/^ +/, (spaces) => "&#32;".repeat(spaces.length));
+	}).join("\\\n");
+}
+function formatMessageTerm(term) {
+	switch (term.type) {
+		case "text": return prose(term.text);
+		case "optionName": return code(term.optionName);
+		case "optionNames": return term.optionNames.map(code).join(", ");
+		case "metavar": return code(term.metavar);
+		case "value": return code(term.value);
+		case "values": return term.values.map(code).join(" ");
+		case "envVar": return code(term.envVar);
+		case "commandLine": return code(term.commandLine);
+		case "url": return code(term.url.href);
+		case "lineBreak": return "\\\n";
+	}
+}
+function formatMessage(message) {
+	let previousCode = false;
+	return message.map((term) => {
+		const content = formatMessageTerm(term);
+		const semanticCode = term.type !== "text" && term.type !== "lineBreak";
+		const separator = previousCode && semanticCode && content !== "" ? "<!-- -->" : "";
+		if (content !== "") previousCode = semanticCode;
+		return separator + content;
+	}).join("").replace(/(?:\\\n)+$/, "");
+}
+function link(label, path) {
+	return `<a href="#${getCommandReferenceAnchor(path)}"><code>${prose(singleLine(label))}</code></a>`;
+}
+function visibleAliases(entry) {
+	const hidden = new Set(entry.hiddenAliases);
+	return [...new Set(entry.aliases)].filter((alias) => !hidden.has(alias) && alias !== entry.path.at(-1));
+}
+function hiddenInTree(entry, index) {
+	for (let length = 1; length <= entry.path.length; length++) if (isDocHidden(index.get(pathKey(entry.path.slice(0, length)))?.hidden)) return true;
+	return false;
+}
+function validateEntries(entries) {
+	const index = /* @__PURE__ */ new Map();
+	const spellings = /* @__PURE__ */ new Map();
+	for (const entry of entries) {
+		const key = pathKey(entry.path);
+		if (index.has(key)) throw new TypeError(`Duplicate command path: ${key}`);
+		index.set(key, entry);
+		for (const alias of [...entry.aliases ?? [], ...entry.hiddenAliases ?? []]) validateToken(alias);
+		if (entry.path.length === 0) {
+			if (entry.aliases?.length || entry.hiddenAliases?.length || entry.hidden) throw new TypeError("The root page cannot have aliases or hidden visibility.");
+			continue;
+		}
+		for (const name of [
+			entry.path.at(-1),
+			...entry.aliases ?? [],
+			...entry.hiddenAliases ?? []
+		]) {
+			const spelling = pathKey([...entry.path.slice(0, -1), name]);
+			const destination = spellings.get(spelling);
+			if (destination != null && destination !== key) throw new TypeError(`Ambiguous command spelling: ${spelling}`);
+			spellings.set(spelling, key);
+		}
+	}
+	return index;
+}
+function commandTarget(entry, parent, index) {
+	return entry.term.type === "command" ? index.get(pathKey([...parent.path, entry.term.name])) : void 0;
+}
+function entryHidden(entry) {
+	return "hidden" in entry.term && isDocHidden(entry.term.hidden);
+}
+function validateCoverage(coverage) {
+	if (coverage == null || !["all-visible", "partial"].includes(coverage.commands) || [
+		coverage.help,
+		coverage.version,
+		coverage.completion
+	].some((value) => value !== "included" && value !== "excluded")) throw new TypeError("Reference coverage must declare commands and runner-added help, version, and completion inputs.");
+}
+/**
+* Renders supplied command pages in caller order as one Markdown reference.
+*
+* Coverage is always author-declared. Visible child references and canonical
+* prefixes are checked, but commands absent from every supplied page cannot be
+* discovered. The renderer never collects pages or evaluates parser callbacks.
+* Messages are documentation text rather than Markdown. Generated anchors and
+* internal links require raw HTML support; bare web/email text may be linkified
+* by a consumer. Every page's usage already includes its command tokens.
+*
+* @param entries Canonical command pages, with explicit aliases and visibility.
+* @param options Program metadata, coverage declaration and presentation policy.
+* @returns A deterministic Markdown document ending in one newline.
+* @throws {TypeError} If paths/aliases are invalid or ambiguous, a canonical
+* path is duplicated, metadata is invalid, or declared complete coverage has
+* missing visible command pages.
+* @since 1.4.0
+*/
+function formatCommandReference(entries, options) {
+	formatUsage(options.name, [], { colors: false });
+	validateCoverage(options.coverage);
+	const index = validateEntries(entries);
+	const visible = entries.filter((entry) => !hiddenInTree(entry, index));
+	const unresolved = options.unresolved?.filter((gap) => !hiddenInTree({
+		path: gap.path,
+		page: { sections: [] }
+	}, index)) ?? [];
+	for (const gap of unresolved) {
+		pathKey(gap.path);
+		if (gap.scope !== "page" && gap.scope !== "subtree") throw new TypeError("An unresolved scope must be page or subtree.");
+	}
+	if (unresolved.length > 0 && options.coverage.commands === "all-visible") throw new TypeError("Unresolved command documentation requires partial coverage.");
+	const missing = /* @__PURE__ */ new Map();
+	if (!index.has("[]")) missing.set("[]", []);
+	for (const entry of visible) {
+		for (let length = 0; length < entry.path.length; length++) {
+			const prefix = entry.path.slice(0, length);
+			if (!index.has(pathKey(prefix))) missing.set(pathKey(prefix), prefix);
+		}
+		for (const section of entry.page.sections) for (const item of section.entries) {
+			if (entryHidden(item) || item.term.type !== "command") continue;
+			const target = commandTarget(item, entry, index);
+			if (target == null) {
+				const path = [...entry.path, item.term.name];
+				missing.set(pathKey(path), path);
+			}
+		}
+	}
+	if (missing.size > 0 && options.coverage.commands === "all-visible") throw new TypeError(`Missing command pages: ${[...missing.values()].map((path) => JSON.stringify(path)).join(", ")}`);
+	const output = [`# ${code(options.name)} command reference`];
+	const addMessage = (content) => {
+		if (content != null && content.length > 0) output.push(formatMessage(content));
+	};
+	if (options.version != null) output.push(`Version: ${code(options.version)}`);
+	addMessage(options.brief);
+	addMessage(options.description);
+	output.push(`Coverage: author-declared ${options.coverage.commands === "all-visible" ? "all visible commands" : "partial command reference"}.`);
+	output.push("Runner inputs: " + [
+		"help",
+		"version",
+		"completion"
+	].map((feature) => `${feature}: ${options.coverage[feature] === "included" ? "included" : "not documented here (if configured)"}`).join("; ") + ".");
+	if (missing.size > 0) output.push("Missing command pages: " + [...missing.values()].map((path) => code([options.name, ...path].join(" "))).join(", ") + ".");
+	if (unresolved.length > 0) output.push("## Unresolved documentation", unresolved.map((gap) => ` -  ${code([options.name, ...gap.path].join(" "))} (${gap.scope}): ${code(gap.reason)}`).join("\n"));
+	output.push("## Contents");
+	output.push(visible.map((entry) => {
+		const fullName = [options.name, ...entry.path].join(" ");
+		const aliases = entry.showAliases ?? options.showAliases ?? false ? visibleAliases(entry).map((alias) => link([
+			options.name,
+			...entry.path.slice(0, -1),
+			alias
+		].join(" "), entry.path)) : [];
+		return ` -  ${link(fullName, entry.path)}${aliases.length > 0 ? ` (aliases: ${aliases.join(", ")})` : ""}`;
+	}).join("\n"));
+	for (const entry of visible) {
+		const page = entry.page;
+		output.push(`<a id="${getCommandReferenceAnchor(entry.path)}"></a>`);
+		output.push(`## ${code([options.name, ...entry.path].join(" "))}`);
+		addMessage(page.brief);
+		if ((options.showUsage ?? page.showUsage ?? true) && page.usage != null) {
+			const usage = formatUsage(options.name, page.usage, { colors: false }).replace(/\r\n?/g, "\n").split("\n").map(singleLine).join("\n");
+			const fence = "~".repeat(Math.max(3, ...Array.from(usage.matchAll(/~+/g), (match) => match[0].length + 1)));
+			output.push("### Usage", `${fence} text\n${usage}\n${fence}`);
+		}
+		addMessage(page.description);
+		for (const section of page.sections) {
+			const items = [];
+			for (const item of section.entries) {
+				if (entryHidden(item)) continue;
+				const target = commandTarget(item, entry, index);
+				if (target != null && hiddenInTree(target, index)) continue;
+				const label = formatUsageTerm(item.term, {
+					context: "doc",
+					colors: false
+				});
+				if (label === "") continue;
+				const aliases = target != null && (item.showAliases ?? target.showAliases ?? options.showAliases ?? false) ? visibleAliases(target).map((alias) => link(alias, target.path)) : [];
+				let content = " -  " + (target == null ? code(label) : link(label, target.path));
+				if (aliases.length > 0) content += ` (aliases: ${aliases.join(", ")})`;
+				const details = [];
+				if (item.description != null) details.push(formatMessage(item.description));
+				if (item.default != null) details.push("Default: " + formatMessage(item.default));
+				if (item.choices != null) details.push("Choices: " + formatMessage(item.choices));
+				if (item.envVars?.length) details.push("Environment: " + item.envVars.map(code).join(", "));
+				if (details.length > 0) content += "\n\n" + details.join("\n\n").split("\n").map((line) => "    " + line).join("\n");
+				items.push(content);
+			}
+			if (items.length > 0) output.push("### " + prose(singleLine(section.title ?? "Inputs")), items.join("\n\n"));
+		}
+		const bindings = page.environmentBindings?.filter((binding) => !isDocHidden(binding.hidden));
+		if (bindings?.length) output.push("### Environment", bindings.map((binding) => ` -  ${code(binding.name)}${binding.description == null ? "" : ": " + formatMessage(binding.description).replaceAll("\n", "\n    ")}`).join("\n"));
+		for (const [title, content] of [
+			["Examples", page.examples],
+			["Author", page.author],
+			["Bugs", page.bugs],
+			["Notes", page.footer]
+		]) if (content != null && content.length > 0) output.push(`### ${title}`, formatMessage(content));
+	}
+	for (const [title, content] of [
+		["Examples", options.examples],
+		["Author", options.author],
+		["Bugs", options.bugs],
+		["Notes", options.footer]
+	]) if (content != null && content.length > 0) output.push(`## ${title}`, formatMessage(content));
+	return output.filter((part) => part !== "").join("\n\n") + "\n";
+}
+
+//#endregion
+export { formatCommandReference, getCommandReferenceAnchor };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@optique/man",
-  "version": "1.4.0-dev.2899",
-  "description": "Man page generator for Optique CLI parsers",
+  "version": "1.4.0-dev.2935",
+  "description": "Man pages and Markdown command references for Optique",
   "keywords": [
     "CLI",
     "command-line",
@@ -77,6 +77,14 @@
       },
       "import": "./dist/cli.js",
       "require": "./dist/cli.cjs"
+    },
+    "./markdown": {
+      "types": {
+        "import": "./dist/markdown.d.ts",
+        "require": "./dist/markdown.d.cts"
+      },
+      "import": "./dist/markdown.js",
+      "require": "./dist/markdown.cjs"
     }
   },
   "imports": {
@@ -90,11 +98,11 @@
     "optique-man": "./dist/cli.js"
   },
   "dependencies": {
-    "@optique/core": "1.4.0-dev.2899+9c2973b0",
-    "@optique/run": "1.4.0-dev.2899+9c2973b0"
+    "@optique/core": "1.4.0-dev.2935+fc126fd1",
+    "@optique/run": "1.4.0-dev.2935+fc126fd1"
   },
   "devDependencies": {
-    "@optique/testing": "1.4.0-dev.2899+9c2973b0",
+    "@optique/testing": "1.4.0-dev.2935+fc126fd1",
     "@types/node": "^24.0.0",
     "tsdown": "^0.13.0",
     "tsx": "^4.21.0",