politty 0.7.0 → 0.8.0

package/dist/docs/index.js

@@ -485,8 +485,10 @@ function renderSubcommandsTableFromArray(subcommands, info, generateAnchors = tr
 		let cmdCell;
 		if (generateAnchors) {
 			const anchor = generateAnchor$1(sub.fullPath);
-			const subFile = fileMap?.[subCommandPath];
+			const hasSubFile = fileMap !== void 0 && Object.prototype.hasOwnProperty.call(fileMap, subCommandPath);
+			const subFile = hasSubFile ? fileMap[subCommandPath] : void 0;
 			if (currentFile && subFile && currentFile !== subFile) cmdCell = `[\`${fullName}\`](${getRelativePath(currentFile, subFile)}#${anchor})`;
+			else if (fileMap && !hasSubFile) cmdCell = `\`${fullName}\``;
 			else cmdCell = `[\`${fullName}\`](#${anchor})`;
 		} else cmdCell = `\`${fullName}\``;
 		if (hasAliases) lines.push(`| ${cmdCell} | ${aliasCell} | ${desc} |`);
@@ -549,14 +551,15 @@ function getGlobalOptionsLink(info) {
 	return `See [Global Options](${info.rootDocPath && info.filePath && info.filePath !== info.rootDocPath ? `${getRelativePath(info.filePath, info.rootDocPath)}#global-options` : "#global-options"}) for options available to all commands.`;
 }
 function createCommandRenderer(options = {}) {
-	const { headingLevel = 1, optionStyle = "table", generateAnchors = true, includeSubcommandDetails = true, renderDescription: customRenderDescription, renderUsage: customRenderUsage, renderArguments: customRenderArguments, renderOptions: customRenderOptions, renderSubcommands: customRenderSubcommands, renderNotes: customRenderNotes, renderFooter: customRenderFooter, renderExamples: customRenderExamples } = options;
+	const { headingLevel = 1, optionStyle = "table", generateAnchors = true, includeSubcommandDetails = true, markerless = false, renderDescription: customRenderDescription, renderUsage: customRenderUsage, renderArguments: customRenderArguments, renderOptions: customRenderOptions, renderSubcommands: customRenderSubcommands, renderNotes: customRenderNotes, renderFooter: customRenderFooter, renderExamples: customRenderExamples } = options;
+	const wrap = markerless ? (_type, _scope, content) => content : wrapWithMarker;
 	return (info) => {
 		const sections = [];
 		const scope = info.commandPath;
 		const effectiveLevel = Math.min(headingLevel + (info.depth - 1), 6);
 		const h = "#".repeat(effectiveLevel);
 		const title = info.commandPath || info.name;
-		sections.push(wrapWithMarker("heading", scope, `${h} ${title}`));
+		sections.push(wrap("heading", scope, `${h} ${title}`));
 		{
 			const parts = [];
 			if (info.description) parts.push(info.description);
@@ -568,7 +571,7 @@ function createCommandRenderer(options = {}) {
 					info
 				};
 				const content = customRenderDescription ? customRenderDescription(context) : context.content;
-				if (content) sections.push(wrapWithMarker("description", scope, content));
+				if (content) sections.push(wrap("description", scope, content));
 			}
 		}
 		{
@@ -578,7 +581,7 @@ function createCommandRenderer(options = {}) {
 				info
 			};
 			const content = customRenderUsage ? customRenderUsage(context) : context.content;
-			if (content) sections.push(wrapWithMarker("usage", scope, content));
+			if (content) sections.push(wrap("usage", scope, content));
 		}
 		if (info.positionalArgs.length > 0) {
 			const renderArgs = (args, opts) => {
@@ -594,7 +597,7 @@ function createCommandRenderer(options = {}) {
 				info
 			};
 			const content = customRenderArguments ? customRenderArguments(context) : renderArgs(context.args);
-			if (content) sections.push(wrapWithMarker("arguments", scope, content));
+			if (content) sections.push(wrap("arguments", scope, content));
 		}
 		if (info.options.length > 0) {
 			const renderOpts = (opts, renderOpts) => {
@@ -614,11 +617,11 @@ function createCommandRenderer(options = {}) {
 				info
 			};
 			const content = customRenderOptions ? customRenderOptions(context) : renderOpts(context.options);
-			if (content) sections.push(wrapWithMarker("options", scope, content));
+			if (content) sections.push(wrap("options", scope, content));
 		}
 		{
 			const globalLink = getGlobalOptionsLink(info);
-			if (globalLink) sections.push(wrapWithMarker("global-options-link", scope, globalLink));
+			if (globalLink) sections.push(wrap("global-options-link", scope, globalLink));
 		}
 		if (info.subCommands.length > 0) {
 			const effectiveAnchors = generateAnchors && includeSubcommandDetails;
@@ -635,7 +638,7 @@ function createCommandRenderer(options = {}) {
 				info
 			};
 			const content = customRenderSubcommands ? customRenderSubcommands(context) : renderSubs(context.subcommands);
-			if (content) sections.push(wrapWithMarker("subcommands", scope, content));
+			if (content) sections.push(wrap("subcommands", scope, content));
 		}
 		if (info.examples && info.examples.length > 0) {
 			const renderEx = (examples, results, opts) => {
@@ -654,7 +657,7 @@ function createCommandRenderer(options = {}) {
 				info
 			};
 			const content = customRenderExamples ? customRenderExamples(context) : renderEx(context.examples, context.results);
-			if (content) sections.push(wrapWithMarker("examples", scope, content));
+			if (content) sections.push(wrap("examples", scope, content));
 		}
 		if (info.notes) {
 			const context = {
@@ -663,7 +666,7 @@ function createCommandRenderer(options = {}) {
 				info
 			};
 			const content = customRenderNotes ? customRenderNotes(context) : context.content;
-			if (content) sections.push(wrapWithMarker("notes", scope, content));
+			if (content) sections.push(wrap("notes", scope, content));
 		}
 		{
 			const context = {
@@ -1090,6 +1093,11 @@ function generateAnchor(commandPath) {
 function isLeafCommand(info) {
 	return info.subCommands.length === 0;
 }
+function isSubcommandOf$1(childPath, parentPath) {
+	if (childPath === parentPath) return true;
+	if (parentPath === "") return childPath !== "";
+	return childPath.startsWith(parentPath + " ");
+}
 /**
 * Expand commands to include their subcommands
 * If a command has subcommands, recursively find all commands under it
@@ -1120,13 +1128,23 @@ function renderCategory(category, allCommands, headingLevel, leafOnly) {
 	lines.push("");
 	lines.push(category.description);
 	lines.push("");
-	const commandPaths = expandCommands(category.commands, allCommands, leafOnly);
+	const commandPaths = category.noExpand ? category.commands : expandCommands(category.commands, allCommands, leafOnly);
+	let visibleCommandPaths = commandPaths;
+	const fallbackCommandPaths = /* @__PURE__ */ new Set();
+	if (category.allowedCommands) {
+		const allowed = new Set(category.allowedCommands);
+		visibleCommandPaths = commandPaths.filter((cmdPath) => allowed.has(cmdPath));
+		for (const configuredPath of category.commands) if (allowed.has(configuredPath) && !visibleCommandPaths.some((cmdPath) => isSubcommandOf$1(cmdPath, configuredPath))) {
+			visibleCommandPaths.push(configuredPath);
+			fallbackCommandPaths.add(configuredPath);
+		}
+	}
 	lines.push("| Command | Description |");
 	lines.push("|---------|-------------|");
-	for (const cmdPath of commandPaths) {
+	for (const cmdPath of visibleCommandPaths) {
 		const info = allCommands.get(cmdPath);
 		if (!info) continue;
-		if (leafOnly && !isLeafCommand(info)) continue;
+		if (!category.noExpand && leafOnly && !fallbackCommandPaths.has(cmdPath) && !isLeafCommand(info)) continue;
 		const displayName = cmdPath || info.name;
 		const anchor = generateAnchor(displayName);
 		const desc = escapeTableCell(info.description ?? "");
@@ -1192,6 +1210,181 @@ function isTruthyEnv(envKey) {
 	const value = process.env[envKey];
 	return value === "true" || value === "1";
 }
+function extractYamlFrontMatter(content) {
+	const lines = content.split(/\r?\n/);
+	if (lines[0] !== "---") return null;
+	const frontMatterLines = [];
+	for (let i = 1; i < lines.length; i++) {
+		const line = lines[i];
+		if (line === "---" || line === "...") return frontMatterLines.join("\n");
+		frontMatterLines.push(line ?? "");
+	}
+	return null;
+}
+function stripPolittyFrontMatterForOutput(content) {
+	const lineEnding = detectLineEnding(content);
+	const lines = content.split(/\r?\n/);
+	if (lines[0] !== "---") return content;
+	let endIndex = -1;
+	for (let i = 1; i < lines.length; i++) {
+		const line = lines[i];
+		if (line === "---" || line === "...") {
+			endIndex = i;
+			break;
+		}
+	}
+	if (endIndex === -1) return content;
+	const frontMatterLines = lines.slice(1, endIndex);
+	const keptFrontMatterLines = [];
+	for (let i = 0; i < frontMatterLines.length; i++) {
+		const line = frontMatterLines[i] ?? "";
+		if (!/^politty\s*:\s*(.*)$/.test(line)) {
+			keptFrontMatterLines.push(line);
+			continue;
+		}
+		while (i + 1 < frontMatterLines.length) {
+			const nextLine = frontMatterLines[i + 1] ?? "";
+			if (nextLine.trim() !== "" && !nextLine.startsWith(" ") && !nextLine.startsWith("	")) break;
+			i++;
+		}
+	}
+	const bodyLines = lines.slice(endIndex + 1);
+	if (!keptFrontMatterLines.some((line) => line.trim() !== "")) return bodyLines.join(lineEnding).replace(new RegExp(`^${lineEnding}`), "");
+	return [
+		"---",
+		...keptFrontMatterLines,
+		lines[endIndex] ?? "---",
+		...bodyLines
+	].join(lineEnding);
+}
+function stripYamlScalarQuotes(value) {
+	const trimmed = value.trim();
+	if (trimmed.length >= 2 && (trimmed.startsWith("\"") && trimmed.endsWith("\"") || trimmed.startsWith("'") && trimmed.endsWith("'"))) return trimmed.slice(1, -1);
+	return trimmed;
+}
+function normalizeTemplatePlaceholderKey(value) {
+	let normalized = stripYamlScalarQuotes(value);
+	if (normalized === "") return null;
+	const fullPlaceholder = normalized.match(/^\{\{politty:([^{}]*)\}\}$/);
+	if (fullPlaceholder) normalized = fullPlaceholder[1] ?? "";
+	else if (normalized.startsWith("politty:")) normalized = normalized.slice(8);
+	return normalized === "" ? null : normalized;
+}
+function templatePlaceholderKey(placeholder) {
+	return placeholder.slice(2, -2).slice(8);
+}
+function splitFrontMatterListValue(value) {
+	const trimmed = value.trim();
+	if (!trimmed.startsWith("[") || !trimmed.endsWith("]")) return [trimmed];
+	return trimmed.slice(1, -1).split(",").map((item) => item.trim()).filter((item) => item.length > 0);
+}
+function addTemplatePlaceholderExclusion(exclusions, value) {
+	const normalized = normalizeTemplatePlaceholderKey(value);
+	if (normalized !== null) exclusions.add(normalized);
+}
+function collectExcludedTemplatePlaceholders(templateContent) {
+	const exclusions = /* @__PURE__ */ new Set();
+	const frontMatter = extractYamlFrontMatter(templateContent);
+	if (frontMatter === null) return exclusions;
+	let inPolittyBlock = false;
+	let inExcludeList = false;
+	let excludeIndent = 0;
+	for (const line of frontMatter.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (trimmed === "" || trimmed.startsWith("#")) continue;
+		const topLevelPolitty = line.match(/^politty\s*:\s*(.*)$/);
+		if (topLevelPolitty) {
+			inPolittyBlock = (topLevelPolitty[1]?.trim() ?? "") === "";
+			inExcludeList = false;
+			continue;
+		}
+		if (!line.startsWith(" ") && !line.startsWith("	")) {
+			inPolittyBlock = false;
+			inExcludeList = false;
+			continue;
+		}
+		if (!inPolittyBlock) continue;
+		const excludeEntry = line.match(/^(\s+)(?:exclude|excludes)\s*:\s*(.*)$/);
+		if (excludeEntry) {
+			const value = excludeEntry[2]?.trim() ?? "";
+			if (value === "") {
+				inExcludeList = true;
+				excludeIndent = excludeEntry[1]?.length ?? 0;
+			} else {
+				inExcludeList = false;
+				for (const item of splitFrontMatterListValue(value)) addTemplatePlaceholderExclusion(exclusions, item);
+			}
+			continue;
+		}
+		if (!inExcludeList) continue;
+		const listItem = line.match(/^(\s*)-\s*(.+)$/);
+		if (!listItem || (listItem[1]?.length ?? 0) <= excludeIndent) {
+			inExcludeList = false;
+			continue;
+		}
+		addTemplatePlaceholderExclusion(exclusions, listItem[2] ?? "");
+	}
+	return exclusions;
+}
+function collectTemplateIndexMetadata(templateContent) {
+	const frontMatter = extractYamlFrontMatter(templateContent);
+	if (frontMatter === null) return {};
+	let inPolittyBlock = false;
+	let inIndexBlock = false;
+	let indexIndent = 0;
+	const metadata = {};
+	for (const line of frontMatter.split(/\r?\n/)) {
+		const trimmed = line.trim();
+		if (trimmed === "" || trimmed.startsWith("#")) continue;
+		const topLevelPolitty = line.match(/^politty\s*:\s*(.*)$/);
+		if (topLevelPolitty) {
+			inPolittyBlock = (topLevelPolitty[1]?.trim() ?? "") === "";
+			inIndexBlock = false;
+			continue;
+		}
+		if (!line.startsWith(" ") && !line.startsWith("	")) {
+			inPolittyBlock = false;
+			inIndexBlock = false;
+			continue;
+		}
+		if (!inPolittyBlock) continue;
+		const indexEntry = line.match(/^(\s+)index\s*:\s*(.*)$/);
+		if (indexEntry) {
+			inIndexBlock = (indexEntry[2]?.trim() ?? "") === "";
+			indexIndent = indexEntry[1]?.length ?? 0;
+			continue;
+		}
+		if (!inIndexBlock) continue;
+		if ((line.match(/^(\s*)/)?.[1]?.length ?? 0) <= indexIndent) {
+			inIndexBlock = false;
+			continue;
+		}
+		const property = line.match(/^\s+(title|description)\s*:\s*(.+)$/);
+		if (!property) continue;
+		const key = property[1];
+		const value = stripYamlScalarQuotes(property[2] ?? "");
+		if (key === "title") metadata.title = value;
+		else if (key === "description") metadata.description = value;
+	}
+	return metadata;
+}
+function createTemplateExclusions(rawKeys) {
+	return {
+		rawKeys,
+		commandScopes: /* @__PURE__ */ new Set(),
+		commandSections: /* @__PURE__ */ new Map(),
+		globalOptions: false,
+		index: false
+	};
+}
+function setFileMapEntry(fileMap, commandPath, filePath) {
+	Object.defineProperty(fileMap, commandPath, {
+		value: filePath,
+		enumerable: true,
+		configurable: true,
+		writable: true
+	});
+}
 /**
 * Normalize file mapping entry to FileConfig
 */
@@ -1546,6 +1739,227 @@ function removeCommandSections(content, commandPath) {
 	return content;
 }
 /**
+* Strip politty marker lines from content, then collapse the blank-line gaps the removed markers
+* leave behind (outside fenced code blocks only, so intentional blank lines inside generated
+* example/code blocks are preserved) and trim leading/trailing blank lines.
+*/
+function stripPolittyMarkers(content) {
+	let result = collapseBlankLinesOutsideCodeFences(content.split("\n").filter((line) => !/^<!-- politty:.*-->$/.test(line.trim())).join("\n"));
+	result = result.replace(/^\n+/, "").replace(/\n+$/, "");
+	return result;
+}
+/**
+* Collapse runs of 3+ newlines to 2, but only outside fenced code blocks so that intentional
+* blank lines inside handwritten code samples are preserved. Fences are lines whose trimmed
+* content starts with ``` or ~~~.
+*/
+function collapseBlankLinesOutsideCodeFences(content) {
+	const lines = content.split("\n");
+	const out = [];
+	let inFence = false;
+	let blankRun = 0;
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (trimmed.startsWith("```") || trimmed.startsWith("~~~")) {
+			inFence = !inFence;
+			blankRun = 0;
+			out.push(line);
+			continue;
+		}
+		if (!inFence && line.trim() === "") {
+			blankRun++;
+			if (blankRun >= 2) continue;
+		} else if (!inFence) blankRun = 0;
+		out.push(line);
+	}
+	return out.join("\n");
+}
+function detectLineEnding(content) {
+	return content.includes("\r\n") ? "\r\n" : "\n";
+}
+function countLineBreaks(value) {
+	return (value.match(/\n/g) ?? []).length;
+}
+/**
+* Type guard for SectionType values parsed from template placeholders.
+*/
+function isSectionType(value) {
+	return SECTION_TYPES.some((type) => type === value);
+}
+/**
+* Clamp a numeric heading level to the valid HeadingLevel range (1–6).
+* Uses a switch to return a literal union member, avoiding `as` assertions.
+*/
+function clampHeadingLevel(level) {
+	switch (Math.min(6, Math.max(1, Math.trunc(level)))) {
+		case 1: return 1;
+		case 2: return 2;
+		case 3: return 3;
+		case 4: return 4;
+		case 5: return 5;
+		default: return 6;
+	}
+}
+function resolveTemplateCommandScope(tokens, allCommands) {
+	if (tokens.length === 0) return allCommands === void 0 || allCommands.has("") ? "" : null;
+	const exactScope = tokens.join(":");
+	if (allCommands?.has(exactScope)) return exactScope;
+	const colonSeparatedScope = tokens.join(" ");
+	if (allCommands?.has(colonSeparatedScope)) return colonSeparatedScope;
+	return allCommands === void 0 ? colonSeparatedScope : null;
+}
+function templateScopeFallback(tokens) {
+	return tokens.join(" ");
+}
+/**
+* Parse a single {{politty:...}} placeholder string into a discriminated structure.
+* The `placeholder` argument should be the full `{{politty:...}}` text.
+*
+* Uses String.match / String.replace internally (not .exec) to avoid lastIndex
+* state issues from the shared TEMPLATE_PLACEHOLDER_REGEX constant.
+*/
+function parsePlaceholder(placeholder, allCommands) {
+	const tokens = placeholder.slice(2, -2).split(":");
+	const directive = tokens[1];
+	if (directive === "command") {
+		const rest = tokens.slice(2);
+		if (rest.length === 1 && rest[0] === "") return {
+			kind: "invalid",
+			reason: `Trailing colon in "${placeholder}"; use {{politty:command}} for the root command.`
+		};
+		const fullScope = resolveTemplateCommandScope(rest, allCommands);
+		if (fullScope !== null) return {
+			kind: "command",
+			scope: fullScope,
+			type: void 0
+		};
+		if (rest.length >= 2) {
+			const last = rest[rest.length - 1];
+			const scopeTokens = rest.slice(0, -1);
+			const sectionScope = resolveTemplateCommandScope(scopeTokens, allCommands);
+			if (last !== void 0 && isSectionType(last)) return {
+				kind: "command",
+				scope: sectionScope ?? templateScopeFallback(scopeTokens),
+				type: last
+			};
+			if (last !== void 0 && sectionScope !== null) return {
+				kind: "invalid",
+				reason: `Unknown section type "${last}" for command scope "${formatCommandPath(sectionScope)}". Valid section types: ${SECTION_TYPES.join(", ")}`
+			};
+		}
+		return {
+			kind: "command",
+			scope: templateScopeFallback(rest),
+			type: void 0
+		};
+	}
+	if (directive === "global-options") {
+		if (tokens.length !== 2) return {
+			kind: "invalid",
+			reason: `Malformed placeholder "${placeholder}". Expected {{politty:global-options}}.`
+		};
+		return { kind: "global-options" };
+	}
+	if (directive === "index") {
+		if (tokens.length !== 2) return {
+			kind: "invalid",
+			reason: `Malformed placeholder "${placeholder}". Expected {{politty:index}}.`
+		};
+		return { kind: "index" };
+	}
+	return {
+		kind: "invalid",
+		reason: `Unknown politty directive "${directive ?? ""}" in "${placeholder}". Valid directives: command, global-options, index`
+	};
+}
+function buildTemplateExclusions(rawKeys, allCommands) {
+	const exclusions = createTemplateExclusions(rawKeys);
+	for (const key of rawKeys) {
+		const parsed = parsePlaceholder(`{{politty:${key}}}`, allCommands);
+		if (parsed.kind === "command") if (parsed.type === void 0) exclusions.commandScopes.add(parsed.scope);
+		else {
+			let sections = exclusions.commandSections.get(parsed.scope);
+			if (!sections) {
+				sections = /* @__PURE__ */ new Set();
+				exclusions.commandSections.set(parsed.scope, sections);
+			}
+			sections.add(parsed.type);
+		}
+		else if (parsed.kind === "global-options") exclusions.globalOptions = true;
+		else if (parsed.kind === "index") exclusions.index = true;
+	}
+	return exclusions;
+}
+function isCommandScopeExcluded(commandPath, excludedCommandScopes) {
+	for (const excludedScope of excludedCommandScopes) if (isSubcommandOf(commandPath, excludedScope)) return true;
+	return false;
+}
+function isCommandSectionExcluded(commandPath, sectionType, exclusions) {
+	if (isCommandScopeExcluded(commandPath, exclusions.commandScopes)) return true;
+	return exclusions.commandSections.get(commandPath)?.has(sectionType) ?? false;
+}
+function getTemplateCommandTreePaths(commandPath, allCommands, ignores, exclusions) {
+	return sortDepthFirst(filterIgnoredCommands(expandCommandPaths([commandPath], allCommands), ignores).filter((path) => !isCommandScopeExcluded(path, exclusions.commandScopes)), [commandPath]);
+}
+function shouldSkipTemplatePlaceholder(placeholder, parsed, exclusions) {
+	if (exclusions.rawKeys.has(templatePlaceholderKey(placeholder))) return true;
+	if (parsed.kind === "command") {
+		if (isCommandScopeExcluded(parsed.scope, exclusions.commandScopes)) return true;
+		return parsed.type !== void 0 && (exclusions.commandSections.get(parsed.scope)?.has(parsed.type) ?? false);
+	}
+	if (parsed.kind === "global-options") return exclusions.globalOptions;
+	if (parsed.kind === "index") return exclusions.index;
+	return false;
+}
+function isRawCommandPlaceholderUnderExcludedScope(key, exclusions) {
+	if (!key.startsWith("command:")) return false;
+	const tokens = key.slice(8).split(":");
+	for (const excludedScope of exclusions.commandScopes) {
+		if (excludedScope === "") return true;
+		const spaceTokens = excludedScope.split(" ");
+		if (tokens.slice(0, spaceTokens.length).join(" ") === excludedScope) return true;
+		const colonTokens = excludedScope.split(":");
+		if (tokens.slice(0, colonTokens.length).join(":") === excludedScope) return true;
+	}
+	return false;
+}
+/**
+* Regex matching {{politty:...}} placeholders.
+* NOTE: only use with String.match / String.replace, never with .exec in a loop,
+* because the /g flag makes the regex stateful via lastIndex.
+*/
+const TEMPLATE_PLACEHOLDER_REGEX = /\{\{politty:[^{}]*\}\}/g;
+function validateTemplatePlaceholderSyntax(templateContent, templatePath) {
+	const validPlaceholderStarts = /* @__PURE__ */ new Set();
+	for (const match of templateContent.matchAll(TEMPLATE_PLACEHOLDER_REGEX)) {
+		const start = match.index;
+		const end = start + match[0].length;
+		if (templateContent[start - 1] === "{" || templateContent[end] === "}") {
+			const snippet = templateContent.slice(Math.max(0, start - 1), Math.min(templateContent.length, end + 1)).split("\n")[0];
+			throw new Error(`Malformed politty placeholder in template "${templatePath}": "${snippet}". Expected {{politty:...}}.`);
+		}
+		validPlaceholderStarts.add(start);
+	}
+	let searchIndex = 0;
+	while (true) {
+		const placeholderStart = templateContent.indexOf("{{politty:", searchIndex);
+		if (placeholderStart === -1) return;
+		if (!validPlaceholderStarts.has(placeholderStart)) {
+			const snippet = templateContent.slice(placeholderStart, placeholderStart + 80).split("\n")[0];
+			throw new Error(`Malformed politty placeholder in template "${templatePath}": "${snippet}". Expected {{politty:...}}.`);
+		}
+		searchIndex = placeholderStart + 10;
+	}
+}
+function getUnknownSectionTypeError(scope, allCommands) {
+	const separatorIndex = scope.lastIndexOf(":");
+	if (separatorIndex === -1) return null;
+	const commandScope = scope.slice(0, separatorIndex);
+	const sectionType = scope.slice(separatorIndex + 1);
+	if (sectionType === "" || !allCommands.has(commandScope)) return null;
+	return `Unknown section type "${sectionType}" for command scope "${formatCommandPath(commandScope)}". Valid section types: ${SECTION_TYPES.join(", ")}`;
+}
+/**
 * Extract a marker section from content
 * Returns the content between start and end markers (including markers)
 */
@@ -1605,6 +2019,17 @@ function normalizeGlobalOptions(config) {
 	return isGlobalOptionsConfigWithOptions(config) ? config : { args: config };
 }
 /**
+* Derive an ArgsShape from a globalArgs Zod schema, retaining only non-positional option fields.
+* Returns undefined when globalArgs is undefined or contains no option fields.
+* Used to build globalOptionDefinitions from globalArgs when rootDoc is not available.
+*/
+function deriveGlobalArgsShape(globalArgs) {
+	if (!globalArgs) return void 0;
+	const optionFields = extractFields(globalArgs).fields.filter((f) => !f.positional);
+	if (optionFields.length === 0) return void 0;
+	return Object.fromEntries(optionFields.map((f) => [f.name, f.schema]));
+}
+/**
 * Collect global option definitions from rootDoc.
 * Global options are intentionally applied to all generated command sections.
 */
@@ -1633,12 +2058,38 @@ function deriveIndexFromFiles(files, rootDocPath, allCommands, ignores) {
 			title: fileConfig?.title ?? cmdInfo?.name ?? path$1.basename(filePath, path$1.extname(filePath)),
 			description: fileConfig?.description ?? cmdInfo?.description ?? "",
 			commands: topLevelCommands,
+			allowedCommands: commandPaths,
 			docPath
 		});
 	}
 	return categories;
 }
 /**
+* Build index categories for the {{politty:index}} placeholder from other template outputs.
+* Each category lists exactly the heading-producing scopes of that output (noExpand), so the
+* index never links to commands that template mode did not render.
+*/
+function deriveIndexFromTemplateOutputs(templateMeta, currentOutputPath, indexFilePath, allCommands) {
+	const normalizedCurrent = normalizeDocPathForComparison(currentOutputPath);
+	const categories = [];
+	for (const [outputPath, meta] of templateMeta.entries()) {
+		if (normalizeDocPathForComparison(outputPath) === normalizedCurrent) continue;
+		const scopes = meta.headingScopes;
+		if (scopes.length === 0) continue;
+		const docPath = "./" + path$1.relative(path$1.dirname(indexFilePath), outputPath).replace(/\\/g, "/");
+		const firstScope = scopes[0];
+		const cmdInfo = firstScope !== void 0 ? allCommands.get(firstScope) : void 0;
+		categories.push({
+			title: meta.indexTitle ?? cmdInfo?.name ?? path$1.basename(outputPath, path$1.extname(outputPath)),
+			description: meta.indexDescription ?? cmdInfo?.description ?? "",
+			commands: scopes,
+			docPath,
+			noExpand: true
+		});
+	}
+	return categories;
+}
+/**
 * Collect command paths that are actually documented in configured files.
 */
 function collectDocumentedCommandPaths(files, allCommands, ignores) {
@@ -1660,6 +2111,15 @@ function collectTargetDocumentedCommandPaths(targetCommands, files, allCommands,
 	}
 	return documentedTargetCommandPaths;
 }
+function commandPathMatchesTarget(commandPath, targetCommands) {
+	return targetCommands.some((targetCommand) => isSubcommandOf(commandPath, targetCommand));
+}
+function templateMetaReferencesCommandTarget(meta, targetCommands) {
+	return meta.referencedScopes.some((scope) => commandPathMatchesTarget(scope, targetCommands));
+}
+function templateMetaShouldProcessForTarget(meta, targetCommands) {
+	return meta.emitsIndex || meta.emitsGlobalOptions || templateMetaReferencesCommandTarget(meta, targetCommands);
+}
 /**
 * Validate that excluded command options match globalOptions definitions.
 */
@@ -1678,16 +2138,19 @@ function validateGlobalOptionCompatibility(documentedCommandPaths, allCommands,
 	if (conflicts.length > 0) throw new Error(`Invalid globalOptions configuration:\n  - ${conflicts.join("\n  - ")}`);
 }
 /**
+* Build global options content (anchor + args table) without markers
+*/
+function buildGlobalOptionsContent(config) {
+	return ["<a id=\"global-options\"></a>", renderArgsTable(config.args, config.options)].join("\n");
+}
+/**
 * Generate global options section content with markers
 */
 function generateGlobalOptionsSection(config) {
-	const startMarker = globalOptionsStartMarker();
-	const endMarker = globalOptionsEndMarker();
 	return [
-		startMarker,
-		"<a id=\"global-options\"></a>",
-		renderArgsTable(config.args, config.options),
-		endMarker
+		globalOptionsStartMarker(),
+		buildGlobalOptionsContent(config),
+		globalOptionsEndMarker()
 	].join("\n");
 }
 /**
@@ -1907,29 +2370,74 @@ function findTargetCommandsInFile(targetCommands, filePath, files, allCommands,
 /**
 * Generate a single command section (already contains section markers from renderer)
 */
-function generateCommandSection(cmdPath, allCommands, render, filePath, fileMap, rootDocPath, hasGlobalOptions) {
+function generateCommandSection(cmdPath, allCommands, render, filePath, fileMap, rootDocPath, hasGlobalOptions, ignores = [], excludeOptionNames, templateExclusions) {
 	const info = allCommands.get(cmdPath);
 	if (!info) return null;
+	if (templateExclusions && isCommandScopeExcluded(info.commandPath, templateExclusions.commandScopes)) return null;
 	const enriched = {
 		...info,
 		filePath,
 		fileMap,
 		rootDocPath
 	};
+	if (ignores.length > 0 || templateExclusions && templateExclusions.commandScopes.size > 0) enriched.subCommands = info.subCommands.filter((sub) => {
+		const subCommandPath = sub.fullPath.join(" ");
+		if (ignores.some((pattern) => matchesIgnorePattern(subCommandPath, pattern))) return false;
+		return !(templateExclusions && isCommandScopeExcluded(subCommandPath, templateExclusions.commandScopes));
+	});
 	if (hasGlobalOptions !== void 0) enriched.hasGlobalOptions = hasGlobalOptions;
-	return render(enriched);
+	if (excludeOptionNames && excludeOptionNames.size > 0) {
+		enriched.options = info.options.filter((opt) => !excludeOptionNames.has(opt.name));
+		if (info.extracted) enriched.extracted = filterExtractedFields(info.extracted, excludeOptionNames);
+	}
+	let rendered = render(enriched);
+	if (templateExclusions) for (const [scope, sectionTypes] of templateExclusions.commandSections) {
+		if (scope !== info.commandPath) continue;
+		for (const sectionType of sectionTypes) {
+			const section = extractSectionMarker(rendered, sectionType, scope);
+			if (section !== null) rendered = rendered.replace(section, "");
+		}
+		rendered = collapseBlankLinesOutsideCodeFences(rendered);
+	}
+	return rendered;
+}
+function generateCommandTreeMarkdown(cmdPath, allCommands, render, ignores, filePath, fileMap, rootDocPath, hasGlobalOptions, excludeOptionNames, templateExclusions) {
+	const commandPaths = getTemplateCommandTreePaths(cmdPath, allCommands, ignores, templateExclusions);
+	const sections = [];
+	for (const commandPath of commandPaths) {
+		const section = generateCommandSection(commandPath, allCommands, render, filePath, fileMap, rootDocPath, hasGlobalOptions, ignores, excludeOptionNames, templateExclusions);
+		if (section !== null) sections.push(section);
+	}
+	return sections.length === 0 ? null : sections.join("\n");
+}
+/**
+* Return a copy of ExtractedFields with the named options removed from every field collection
+* (top-level fields, union options, and discriminated-union variants). Used to exclude global
+* options from grouped option tables rendered directly from `extracted`.
+*/
+function filterExtractedFields(extracted, excludeOptionNames) {
+	const result = {
+		...extracted,
+		fields: extracted.fields.filter((f) => !excludeOptionNames.has(f.name))
+	};
+	if (extracted.unionOptions) result.unionOptions = extracted.unionOptions.map((opt) => filterExtractedFields(opt, excludeOptionNames));
+	if (extracted.variants) result.variants = extracted.variants.map((variant) => ({
+		...variant,
+		fields: variant.fields.filter((f) => !excludeOptionNames.has(f.name))
+	}));
+	return result;
 }
 /**
 * Generate markdown for a file containing multiple commands
 * Each command section is wrapped with markers for partial validation
 */
-function generateFileMarkdown(commandPaths, allCommands, render, filePath, fileMap, specifiedOrder, fileConfig, rootDocPath, hasGlobalOptions) {
+function generateFileMarkdown(commandPaths, allCommands, render, filePath, fileMap, specifiedOrder, fileConfig, rootDocPath, hasGlobalOptions, ignores = []) {
 	const sections = [];
 	const header = fileConfig ? generateFileHeader(fileConfig) : null;
 	if (header) sections.push(header);
 	const sortedPaths = sortDepthFirst(commandPaths, specifiedOrder ?? []);
 	for (const cmdPath of sortedPaths) {
-		const section = generateCommandSection(cmdPath, allCommands, render, filePath, fileMap, rootDocPath, hasGlobalOptions);
+		const section = generateCommandSection(cmdPath, allCommands, render, filePath, fileMap, rootDocPath, hasGlobalOptions, ignores);
 		if (section) sections.push(section);
 	}
 	return `${sections.join("\n")}\n`;
@@ -1941,7 +2449,7 @@ function buildFileMap(files, allCommands, ignores) {
 	const fileMap = {};
 	for (const [filePath, fileConfigRaw] of Object.entries(files)) {
 		const { commandPaths } = resolveConfiguredCommandPaths(fileConfigRaw, allCommands, ignores);
-		for (const cmdPath of commandPaths) fileMap[cmdPath] = filePath;
+		for (const cmdPath of commandPaths) setFileMapEntry(fileMap, cmdPath, filePath);
 	}
 	return fileMap;
 }
@@ -1994,7 +2502,7 @@ function pathToFiles(pathConfig, allCommands) {
 * Generate documentation from command definition
 */
 async function generateDoc(config) {
-	const { command, ignores = [], format = {}, formatter, examples: examplesConfig, targetCommands, globalArgs } = config;
+	const { command, ignores = [], format = {}, formatter, examples: examplesConfig, targetCommands, globalArgs, customizable = false } = config;
 	const allCommands = await collectAllCommands(command);
 	let files;
 	let usingPathConfig = false;
@@ -2006,7 +2514,8 @@ async function generateDoc(config) {
 		resolvedRootDocPath = converted.rootDocPath;
 		usingPathConfig = true;
 	} else if (config.files !== void 0) files = config.files;
-	else throw new Error("Either \"path\" or \"files\" must be specified.");
+	else if (config.templates !== void 0) files = {};
+	else throw new Error("Either \"path\", \"files\", or \"templates\" must be specified.");
 	let rootDoc = config.rootDoc;
 	if (!rootDoc && usingPathConfig && (globalArgs || config.rootInfo)) rootDoc = { path: resolvedRootDocPath };
 	if (globalArgs && rootDoc && !rootDoc.globalOptions) {
@@ -2028,12 +2537,14 @@ async function generateDoc(config) {
 	}
 	if (examplesConfig) await executeConfiguredExamples(allCommands, examplesConfig, command);
 	const hasTargetCommands = targetCommands !== void 0 && targetCommands.length > 0;
-	if (hasTargetCommands) {
-		for (const targetCommand of targetCommands) if (!findFileForCommand(targetCommand, files, allCommands, ignores)) throw new Error(`Target command "${targetCommand}" not found in any file configuration`);
-	}
 	const globalOptionDefinitions = collectGlobalOptionDefinitions(rootDoc);
-	validateGlobalOptionCompatibility(hasTargetCommands ? collectTargetDocumentedCommandPaths(targetCommands, files, allCommands, ignores) : collectDocumentedCommandPaths(files, allCommands, ignores), allCommands, globalOptionDefinitions);
-	if (globalOptionDefinitions.size > 0) for (const info of allCommands.values()) info.options = info.options.filter((opt) => !globalOptionDefinitions.has(opt.name));
+	const templateGlobalOptionFields = /* @__PURE__ */ new Map();
+	if (config.templates) if (globalOptionDefinitions.size > 0) for (const [name, field] of globalOptionDefinitions) templateGlobalOptionFields.set(name, field);
+	else {
+		const shape = deriveGlobalArgsShape(globalArgs);
+		if (shape) for (const field of collectRenderableGlobalOptionFields(shape)) templateGlobalOptionFields.set(field.name, field);
+	}
+	const documentedCommandPaths = hasTargetCommands ? collectTargetDocumentedCommandPaths(targetCommands, files, allCommands, ignores) : collectDocumentedCommandPaths(files, allCommands, ignores);
 	const allFilesCommands = [];
 	for (const fileConfigRaw of Object.values(files)) {
 		const fileConfig = normalizeFileConfig(fileConfigRaw);
@@ -2042,6 +2553,159 @@ async function generateDoc(config) {
 	validateIgnoresExist(ignores, allCommands);
 	validateNoConflicts(allFilesCommands, ignores, allCommands);
 	const fileMap = buildFileMap(files, allCommands, ignores);
+	const templateContents = /* @__PURE__ */ new Map();
+	const templateExclusions = /* @__PURE__ */ new Map();
+	if (config.templates) for (const [outputPath, templatePath] of Object.entries(config.templates)) {
+		const templateContent = readFile(templatePath);
+		templateContents.set(outputPath, templateContent);
+		if (templateContent !== null) templateExclusions.set(outputPath, buildTemplateExclusions(collectExcludedTemplatePlaceholders(templateContent), allCommands));
+	}
+	const templateEntries = Object.entries(config.templates ?? {});
+	const templateMeta = /* @__PURE__ */ new Map();
+	const templateValidationErrors = /* @__PURE__ */ new Map();
+	if (templateEntries.length > 0) {
+		const normalizedRootDocPath = rootDoc ? normalizeDocPathForComparison(rootDoc.path) : null;
+		const normalizedFileKeys = new Set(Object.keys(files).map(normalizeDocPathForComparison));
+		const normalizedTemplateOutputs = /* @__PURE__ */ new Set();
+		const allNormalizedTemplateOutputs = new Set(templateEntries.map(([outputPath]) => normalizeDocPathForComparison(outputPath)));
+		for (const [outputPath, templatePath] of templateEntries) {
+			const normalizedOutput = normalizeDocPathForComparison(outputPath);
+			const normalizedSource = normalizeDocPathForComparison(templatePath);
+			if (normalizedFileKeys.has(normalizedOutput)) throw new Error(`Template output path "${outputPath}" conflicts with an existing files key.`);
+			if (normalizedRootDocPath && normalizedOutput === normalizedRootDocPath) throw new Error(`Template output path "${outputPath}" conflicts with rootDoc.path "${rootDoc.path}".`);
+			if (normalizedTemplateOutputs.has(normalizedOutput)) throw new Error(`Duplicate template output path: "${outputPath}".`);
+			normalizedTemplateOutputs.add(normalizedOutput);
+			if (normalizedSource === normalizedOutput) throw new Error(`Template output path "${outputPath}" must not be the same as its source template path.`);
+			if (normalizedFileKeys.has(normalizedSource)) throw new Error(`Template source path "${templatePath}" conflicts with a files output key.`);
+			if (normalizedRootDocPath && normalizedSource === normalizedRootDocPath) throw new Error(`Template source path "${templatePath}" conflicts with rootDoc.path "${rootDoc.path}".`);
+			if (allNormalizedTemplateOutputs.has(normalizedSource)) throw new Error(`Template source path "${templatePath}" conflicts with a template output path.`);
+		}
+		const availableCommandPaths = Array.from(allCommands.keys()).join(", ");
+		for (const [outputPath, templatePath] of templateEntries) {
+			const templateContent = templateContents.get(outputPath) ?? null;
+			const validationErrors = [];
+			if (templateContent === null) {
+				templateMeta.set(outputPath, {
+					referencedScopes: [],
+					headingScopes: [],
+					commandTreeRoots: [],
+					emitsGlobalOptions: false,
+					emitsIndex: false
+				});
+				templateValidationErrors.set(outputPath, validationErrors);
+				continue;
+			}
+			try {
+				validateTemplatePlaceholderSyntax(templateContent, templatePath);
+			} catch (error) {
+				validationErrors.push(error instanceof Error ? error.message : String(error));
+			}
+			const placeholders = Array.from(new Set(templateContent.match(TEMPLATE_PLACEHOLDER_REGEX) ?? []));
+			const scopes = /* @__PURE__ */ new Set();
+			const headingScopes = /* @__PURE__ */ new Set();
+			const commandTreeRoots = /* @__PURE__ */ new Set();
+			let emitsGlobalOptions = false;
+			let emitsIndex = false;
+			const exclusions = templateExclusions.get(outputPath) ?? createTemplateExclusions(/* @__PURE__ */ new Set());
+			const indexMetadata = collectTemplateIndexMetadata(templateContent);
+			for (const placeholder of placeholders) {
+				const placeholderKey = templatePlaceholderKey(placeholder);
+				if (exclusions.rawKeys.has(placeholderKey) || isRawCommandPlaceholderUnderExcludedScope(placeholderKey, exclusions)) continue;
+				const parsed = parsePlaceholder(placeholder, allCommands);
+				if (shouldSkipTemplatePlaceholder(placeholder, parsed, exclusions)) continue;
+				if (parsed.kind === "invalid") {
+					validationErrors.push(`${parsed.reason} (in template "${templatePath}")`);
+					continue;
+				}
+				if (parsed.kind === "command") {
+					const { scope, type } = parsed;
+					if (!allCommands.has(scope)) {
+						const sectionTypeError = getUnknownSectionTypeError(scope, allCommands);
+						if (sectionTypeError) {
+							validationErrors.push(`${sectionTypeError} (in template "${templatePath}")`);
+							continue;
+						}
+						validationErrors.push(`Unknown command scope "${scope}" in template "${templatePath}". Available: ${availableCommandPaths}`);
+						continue;
+					}
+					if (ignores.some((pattern) => matchesIgnorePattern(scope, pattern))) {
+						validationErrors.push(`Command scope "${scope}" in template "${templatePath}" conflicts with ignores configuration.`);
+						continue;
+					}
+					if (type === void 0) {
+						const commandTreePaths = getTemplateCommandTreePaths(scope, allCommands, ignores, exclusions);
+						if (!isCommandSectionExcluded(scope, "heading", exclusions)) commandTreeRoots.add(scope);
+						for (const commandTreePath of commandTreePaths) {
+							scopes.add(commandTreePath);
+							if (!isCommandSectionExcluded(commandTreePath, "heading", exclusions)) headingScopes.add(commandTreePath);
+						}
+					} else {
+						scopes.add(scope);
+						if (type === "heading" && !isCommandSectionExcluded(scope, "heading", exclusions)) {
+							headingScopes.add(scope);
+							commandTreeRoots.add(scope);
+						}
+					}
+				} else if (parsed.kind === "global-options") emitsGlobalOptions = true;
+				else if (parsed.kind === "index") emitsIndex = true;
+			}
+			if (emitsGlobalOptions) {
+				if (!(!!rootDoc?.globalOptions || deriveGlobalArgsShape(globalArgs) !== void 0)) validationErrors.push(`Template "${templatePath}" uses {{politty:global-options}} but no global options are configured (neither rootDoc.globalOptions nor globalArgs with non-positional options).`);
+			}
+			templateMeta.set(outputPath, {
+				referencedScopes: Array.from(scopes),
+				headingScopes: Array.from(headingScopes),
+				commandTreeRoots: Array.from(commandTreeRoots),
+				emitsGlobalOptions,
+				emitsIndex,
+				...indexMetadata.title !== void 0 ? { indexTitle: indexMetadata.title } : {},
+				...indexMetadata.description !== void 0 ? { indexDescription: indexMetadata.description } : {}
+			});
+			templateValidationErrors.set(outputPath, validationErrors);
+		}
+		for (const meta of templateMeta.values()) {
+			if (hasTargetCommands && !templateMetaShouldProcessForTarget(meta, targetCommands)) continue;
+			for (const scope of meta.referencedScopes) documentedCommandPaths.add(scope);
+		}
+	}
+	if (hasTargetCommands) for (const targetCommand of targetCommands) {
+		const targetFilePath = findFileForCommand(targetCommand, files, allCommands, ignores);
+		const targetTemplatePath = Array.from(templateMeta.values()).some((meta) => templateMetaReferencesCommandTarget(meta, [targetCommand]));
+		if (!targetFilePath && !targetTemplatePath) throw new Error(`Target command "${targetCommand}" not found in any file or template configuration`);
+	}
+	const activeTemplateMeta = hasTargetCommands && config.templates ? new Map(Array.from(templateMeta.entries()).filter(([, meta]) => templateMetaShouldProcessForTarget(meta, targetCommands))) : templateMeta;
+	for (const [outputPath, validationErrors] of templateValidationErrors.entries()) if (validationErrors.length > 0 && activeTemplateMeta.has(outputPath)) throw new Error(validationErrors.join("\n"));
+	const templateGlobalOptionsProviderPaths = Array.from(templateMeta.entries()).filter(([, meta]) => meta.emitsGlobalOptions).map(([outputPath]) => outputPath);
+	const templateGlobalOptionsProviderPath = templateGlobalOptionsProviderPaths.length === 1 ? templateGlobalOptionsProviderPaths[0] : void 0;
+	validateGlobalOptionCompatibility(documentedCommandPaths, allCommands, globalOptionDefinitions);
+	if (globalOptionDefinitions.size === 0 && templateGlobalOptionFields.size > 0) {
+		const emittingTemplateScopes = /* @__PURE__ */ new Set();
+		for (const meta of activeTemplateMeta.values()) {
+			if (!meta.emitsGlobalOptions && templateGlobalOptionsProviderPath === void 0) continue;
+			for (const scope of meta.referencedScopes) emittingTemplateScopes.add(scope);
+		}
+		validateGlobalOptionCompatibility(emittingTemplateScopes, allCommands, templateGlobalOptionFields);
+	}
+	if (globalOptionDefinitions.size > 0) for (const info of allCommands.values()) {
+		info.options = info.options.filter((opt) => !globalOptionDefinitions.has(opt.name));
+		if (info.extracted) info.extracted = filterExtractedFields(info.extracted, new Set(globalOptionDefinitions.keys()));
+	}
+	const templateFileMap = {};
+	for (const [scope, outputPath] of Object.entries(fileMap)) setFileMapEntry(templateFileMap, scope, outputPath);
+	const scopeRootLength = (root) => root === "" ? 0 : root.split(" ").length;
+	const templateOwners = /* @__PURE__ */ new Map();
+	for (const [templateOutputPath, meta] of templateMeta.entries()) for (const scope of meta.headingScopes) {
+		if (Object.prototype.hasOwnProperty.call(fileMap, scope)) continue;
+		let bestRootLen = -1;
+		for (const root of meta.commandTreeRoots) if (isSubcommandOf(scope, root)) bestRootLen = Math.max(bestRootLen, scopeRootLength(root));
+		if (bestRootLen < 0) continue;
+		const existing = templateOwners.get(scope);
+		if (!existing || bestRootLen > existing.rootLen) templateOwners.set(scope, {
+			outputPath: templateOutputPath,
+			rootLen: bestRootLen
+		});
+	}
+	for (const [scope, { outputPath }] of templateOwners) setFileMapEntry(templateFileMap, scope, outputPath);
 	const results = [];
 	let hasError = false;
 	for (const [filePath, fileConfigRaw] of Object.entries(files)) {
@@ -2054,18 +2718,20 @@ async function generateDoc(config) {
 		const diffs = [];
 		const minDepth = Math.min(...commandPaths.map((p) => allCommands.get(p)?.depth ?? 1));
 		const adjustedHeadingLevel = Math.max(1, (format?.headingLevel ?? 1) - (minDepth - 1));
+		const isRootDocFile = usingPathConfig && rootDoc && normalizeDocPathForComparison(filePath) === normalizeDocPathForComparison(rootDoc.path);
+		const fileUsesMarkers = usingPathConfig || customizable;
 		const fileRenderer = createCommandRenderer({
 			...format,
-			headingLevel: adjustedHeadingLevel
+			headingLevel: adjustedHeadingLevel,
+			markerless: !fileUsesMarkers
 		});
 		const render = fileConfig.render ?? fileRenderer;
-		const isRootDocFile = usingPathConfig && rootDoc && normalizeDocPathForComparison(filePath) === normalizeDocPathForComparison(rootDoc.path);
-		if (hasTargetCommands || isRootDocFile) {
+		if (Boolean(isRootDocFile) || hasTargetCommands && fileUsesMarkers) {
 			let existingContent = readFile(filePath);
 			const sortedCommandPaths = sortDepthFirst(commandPaths, specifiedCommands);
 			const effectiveTargetCommands = hasTargetCommands ? fileTargetCommands : commandPaths;
 			for (const targetCommand of effectiveTargetCommands) {
-				const rawSection = generateCommandSection(targetCommand, allCommands, render, filePath, fileMap, rootDoc?.path, globalOptionDefinitions.size > 0);
+				const rawSection = generateCommandSection(targetCommand, allCommands, render, filePath, templateFileMap, rootDoc?.path, globalOptionDefinitions.size > 0, ignores);
 				if (!rawSection) throw new Error(`Target command "${targetCommand}" not found in commands`);
 				const generatedSection = await applyFormatter(rawSection, formatter);
 				if (!existingContent) {
@@ -2127,23 +2793,23 @@ async function generateDoc(config) {
 						diffs.push(formatDiff(existingSection, generatedSectionPart));
 					}
 				}
-				if (doctorMode) {
+				if (doctorMode || customizable) {
 					const generatedMarkers = collectSectionMarkers(generatedSection, targetCommand);
 					const existingMarkerSet = new Set(existingMarkers);
 					for (const sectionType of generatedMarkers) {
 						if (existingMarkerSet.has(sectionType)) continue;
 						const generatedSectionPart = extractSectionMarker(generatedSection, sectionType, targetCommand);
 						if (!generatedSectionPart) continue;
-						if (updateMode) {
+						if (doctorMode && updateMode) {
 							existingContent = insertSectionMarkerAtOrder(existingContent, sectionType, targetCommand, generatedSectionPart);
 							writeFile(filePath, existingContent);
 							if (fileStatus !== "created") fileStatus = "updated";
-						} else {
+						} else if (doctorMode) {
 							hasError = true;
 							hasDoctorIssues = true;
 							fileStatus = "diff";
 							diffs.push(`[doctor] Missing section marker "${sectionType}" for command "${formatCommandPath(targetCommand)}". Run with ${DOCTOR_ENV}=true ${UPDATE_GOLDEN_ENV}=true to insert.\n${generatedSectionPart}`);
-						}
+						} else console.warn(`[politty] Missing "${sectionType}" section for command "${formatCommandPath(targetCommand)}" in ${filePath}. Run with ${DOCTOR_ENV}=true ${UPDATE_GOLDEN_ENV}=true to insert it, or leave it removed to opt that section out.`);
 					}
 				}
 			}
@@ -2167,7 +2833,7 @@ async function generateDoc(config) {
 				}
 			}
 		} else {
-			const generatedMarkdown = await applyFormatter(generateFileMarkdown(commandPaths, allCommands, render, filePath, fileMap, specifiedCommands, fileConfig, rootDoc?.path, globalOptionDefinitions.size > 0), formatter);
+			const generatedMarkdown = await applyFormatter(generateFileMarkdown(commandPaths, allCommands, render, filePath, templateFileMap, specifiedCommands, fileConfig, rootDoc?.path, globalOptionDefinitions.size > 0, ignores), formatter);
 			const comparison = compareWithExisting(generatedMarkdown, filePath);
 			if (comparison.match) {} else if (updateMode) {
 				writeFile(filePath, generatedMarkdown);
@@ -2185,6 +2851,112 @@ async function generateDoc(config) {
 			diff: diffs.length > 0 ? diffs.join("\n\n") : void 0
 		});
 	}
+	let normalizedTemplateGlobalOptions;
+	if (rootDoc?.globalOptions) normalizedTemplateGlobalOptions = normalizeGlobalOptions(rootDoc.globalOptions);
+	else {
+		const shape = deriveGlobalArgsShape(globalArgs);
+		if (shape) normalizedTemplateGlobalOptions = { args: shape };
+	}
+	for (const [outputPath, templatePath] of templateEntries) {
+		if (!activeTemplateMeta.has(outputPath)) continue;
+		const templateContent = templateContents.get(outputPath) ?? null;
+		if (templateContent === null) {
+			hasError = true;
+			results.push({
+				path: outputPath,
+				status: "diff",
+				diff: `Template file not found: ${templatePath}`
+			});
+			continue;
+		}
+		const meta = templateMeta.get(outputPath);
+		const templateLineEnding = detectLineEnding(templateContent);
+		const outputTemplateContent = stripPolittyFrontMatterForOutput(templateContent);
+		const headingDepths = (meta?.headingScopes ?? []).map((s) => allCommands.get(s)?.depth ?? 1);
+		const minDepth = headingDepths.length > 0 ? Math.min(...headingDepths) : 1;
+		const adjustedHeadingLevel = clampHeadingLevel((format?.headingLevel ?? 1) - (minDepth - 1));
+		const templateRenderer = createCommandRenderer({
+			...format,
+			headingLevel: adjustedHeadingLevel
+		});
+		const outputEmitsGlobalOptions = meta?.emitsGlobalOptions ?? false;
+		const excludeOptionNames = (rootDoc !== void 0 && globalOptionDefinitions.size > 0 || outputEmitsGlobalOptions || templateGlobalOptionsProviderPath !== void 0) && templateGlobalOptionFields.size > 0 ? new Set(templateGlobalOptionFields.keys()) : void 0;
+		const sectionHasGlobalOptions = excludeOptionNames !== void 0;
+		const effectiveRootDocPath = outputEmitsGlobalOptions ? outputPath : rootDoc?.path ?? templateGlobalOptionsProviderPath;
+		const placeholders = Array.from(new Set(outputTemplateContent.match(TEMPLATE_PLACEHOLDER_REGEX) ?? []));
+		const replacements = /* @__PURE__ */ new Map();
+		const exclusions = templateExclusions.get(outputPath) ?? createTemplateExclusions(/* @__PURE__ */ new Set());
+		for (const placeholder of placeholders) {
+			const placeholderKey = templatePlaceholderKey(placeholder);
+			if (exclusions.rawKeys.has(placeholderKey) || isRawCommandPlaceholderUnderExcludedScope(placeholderKey, exclusions)) {
+				replacements.set(placeholder, "");
+				continue;
+			}
+			const parsed = parsePlaceholder(placeholder, allCommands);
+			if (shouldSkipTemplatePlaceholder(placeholder, parsed, exclusions)) {
+				replacements.set(placeholder, "");
+				continue;
+			}
+			if (parsed.kind === "invalid") throw new Error(`Internal error: unresolved placeholder "${placeholder}" in template "${templatePath}": ${parsed.reason}`);
+			if (parsed.kind === "command") {
+				const { scope, type } = parsed;
+				if (type === void 0) {
+					const rawSection = generateCommandTreeMarkdown(scope, allCommands, templateRenderer, ignores, outputPath, templateFileMap, effectiveRootDocPath, sectionHasGlobalOptions, excludeOptionNames, exclusions);
+					if (rawSection === null) {
+						replacements.set(placeholder, "");
+						continue;
+					}
+					replacements.set(placeholder, stripPolittyMarkers(rawSection));
+				} else {
+					const rawSection = generateCommandSection(scope, allCommands, templateRenderer, outputPath, templateFileMap, effectiveRootDocPath, sectionHasGlobalOptions, ignores, excludeOptionNames, exclusions);
+					if (rawSection === null) {
+						replacements.set(placeholder, "");
+						continue;
+					}
+					const extracted = extractSectionMarker(rawSection, type, scope);
+					replacements.set(placeholder, extracted === null ? "" : stripPolittyMarkers(extracted));
+				}
+			} else if (parsed.kind === "global-options") if (normalizedTemplateGlobalOptions) replacements.set(placeholder, buildGlobalOptionsContent(normalizedTemplateGlobalOptions));
+			else replacements.set(placeholder, "");
+			else if (parsed.kind === "index") {
+				const indexContent = await renderCommandIndex(command, [...deriveIndexFromFiles(files, outputPath, allCommands, ignores), ...deriveIndexFromTemplateOutputs(templateMeta, outputPath, outputPath, allCommands)], rootDoc?.index);
+				replacements.set(placeholder, indexContent);
+			}
+		}
+		let generated = outputTemplateContent.replace(/((?:\r?\n)*)([ \t]*)(\{\{politty:[^{}]*\}\})([ \t]*)((?:\r?\n)*)/g, (match, leadNl, leadWs, placeholder, trailWs, trailNl, offset, fullString) => {
+			const replacement = replacements.get(placeholder);
+			if (replacement === void 0) throw new Error(`Internal error: unresolved placeholder "${placeholder}" in template "${templatePath}".`);
+			const startsLine = leadNl !== "" || offset === 0 || fullString[offset - 1] === "\n";
+			const endsLine = trailNl !== "" || offset + match.length === fullString.length;
+			if (replacement === "" && startsLine && endsLine) {
+				if (leadNl === "" || trailNl === "") return "";
+				const leadBreaks = countLineBreaks(leadNl);
+				const trailBreaks = countLineBreaks(trailNl);
+				const widest = Math.max(leadBreaks, trailBreaks);
+				const lineEnding = leadBreaks >= trailBreaks ? detectLineEnding(leadNl) : detectLineEnding(trailNl);
+				return widest >= 2 ? lineEnding + lineEnding : widest === 1 ? lineEnding : "";
+			}
+			return `${leadNl}${leadWs}${replacement}${trailWs}${trailNl}`;
+		});
+		generated = `${generated.trimEnd()}${templateLineEnding}`;
+		generated = await applyFormatter(generated, formatter);
+		const comparison = compareWithExisting(generated, outputPath);
+		let templateStatus = "match";
+		let templateDiff;
+		if (comparison.match) {} else if (updateMode) {
+			writeFile(outputPath, generated);
+			templateStatus = comparison.fileExists ? "updated" : "created";
+		} else {
+			hasError = true;
+			templateStatus = "diff";
+			if (comparison.diff) templateDiff = comparison.diff;
+		}
+		results.push({
+			path: outputPath,
+			status: templateStatus,
+			diff: templateDiff
+		});
+	}
 	if (rootDoc) {
 		const rootDocFilePath = rootDoc.path;
 		let rootDocStatus = "match";
@@ -2290,7 +3062,19 @@ async function assertDocMatch(config) {
 function initDocFile(config, fileSystem) {
 	if (!isTruthyEnv("POLITTY_DOCS_UPDATE")) return;
 	if (typeof config === "string") deleteFile(config, fileSystem);
-	else if (config.files) for (const filePath of Object.keys(config.files)) deleteFile(filePath, fileSystem);
+	else {
+		const protectedPaths = new Set(Object.values(config.templates ?? {}).map(normalizeDocPathForComparison));
+		if (config.rootDoc) protectedPaths.add(normalizeDocPathForComparison(config.rootDoc.path));
+		const isProtectedPath = (p) => protectedPaths.has(normalizeDocPathForComparison(p));
+		if (config.files) for (const filePath of Object.keys(config.files)) {
+			if (isProtectedPath(filePath)) continue;
+			deleteFile(filePath, fileSystem);
+		}
+		if (config.templates) for (const outputPath of Object.keys(config.templates)) {
+			if (isProtectedPath(outputPath)) continue;
+			deleteFile(outputPath, fileSystem);
+		}
+	}
 }
 
 //#endregion