politty 0.3.3 → 0.4.0

package/dist/docs/index.cjs

@@ -8,6 +8,77 @@ node_fs = require_subcommand_router.__toESM(node_fs);
 let node_path = require("node:path");
 node_path = require_subcommand_router.__toESM(node_path);
 
+//#region src/docs/types.ts
+/**
+* Environment variable name for update mode
+*/
+const UPDATE_GOLDEN_ENV = "POLITTY_DOCS_UPDATE";
+/**
+* All section types in rendering order
+*/
+const SECTION_TYPES = [
+	"heading",
+	"description",
+	"usage",
+	"arguments",
+	"options",
+	"subcommands",
+	"examples",
+	"notes"
+];
+/**
+* Marker prefix for command section markers in generated documentation
+* Format: <!-- politty:command:<scope>:<type>:start --> ... <!-- politty:command:<scope>:<type>:end -->
+*/
+const SECTION_MARKER_PREFIX = "politty:command";
+/**
+* Generate start marker for a command section
+*/
+function sectionStartMarker(type, scope) {
+	return `<!-- ${SECTION_MARKER_PREFIX}:${scope}:${type}:start -->`;
+}
+/**
+* Generate end marker for a command section
+*/
+function sectionEndMarker(type, scope) {
+	return `<!-- ${SECTION_MARKER_PREFIX}:${scope}:${type}:end -->`;
+}
+/**
+* Marker prefix for global options sections in generated documentation
+* Format: <!-- politty:global-options:start --> ... <!-- politty:global-options:end -->
+*/
+const GLOBAL_OPTIONS_MARKER_PREFIX = "politty:global-options";
+/**
+* Generate start marker for a global options section
+*/
+function globalOptionsStartMarker() {
+	return `<!-- ${GLOBAL_OPTIONS_MARKER_PREFIX}:start -->`;
+}
+/**
+* Generate end marker for a global options section
+*/
+function globalOptionsEndMarker() {
+	return `<!-- ${GLOBAL_OPTIONS_MARKER_PREFIX}:end -->`;
+}
+/**
+* Marker prefix for index sections in generated documentation
+* Format: <!-- politty:index:<scope>:start --> ... <!-- politty:index:<scope>:end -->
+*/
+const INDEX_MARKER_PREFIX = "politty:index";
+/**
+* Generate start marker for an index section
+*/
+function indexStartMarker(scope) {
+	return `<!-- ${INDEX_MARKER_PREFIX}:${scope}:start -->`;
+}
+/**
+* Generate end marker for an index section
+*/
+function indexEndMarker(scope) {
+	return `<!-- ${INDEX_MARKER_PREFIX}:${scope}:end -->`;
+}
+
+//#endregion
 //#region src/docs/default-renderers.ts
 /**
 * Escape markdown special characters in table cells
@@ -69,15 +140,34 @@ function formatEnvInfo(env) {
 	return ` [env: ${(Array.isArray(env) ? env : [env]).join(", ")}]`;
 }
 /**
-* Format option flags (uses kebab-case cliName)
+* Resolve placeholder for an option (uses kebab-case cliName)
+*/
+function resolvePlaceholder(opt) {
+	return opt.placeholder ?? opt.cliName.toUpperCase().replace(/-/g, "_");
+}
+/**
+* Format option name for table display (e.g., `--dry-run` or `--port <PORT>`)
+*/
+function formatOptionName(opt) {
+	const placeholder = resolvePlaceholder(opt);
+	return opt.type === "boolean" ? `\`--${opt.cliName}\`` : `\`--${opt.cliName} <${placeholder}>\``;
+}
+/**
+* Format option flags for list display (uses kebab-case cliName)
 */
 function formatOptionFlags(opt) {
-	const parts = [];
-	const placeholder = opt.placeholder ?? opt.cliName.toUpperCase().replace(/-/g, "_");
+	const placeholder = resolvePlaceholder(opt);
 	const longFlag = opt.type === "boolean" ? `--${opt.cliName}` : `--${opt.cliName} <${placeholder}>`;
-	if (opt.alias) parts.push(`\`-${opt.alias}\`, \`${longFlag}\``);
-	else parts.push(`\`${longFlag}\``);
-	return parts.join("");
+	if (opt.alias) return `\`-${opt.alias}\`, \`${longFlag}\``;
+	return `\`${longFlag}\``;
+}
+/**
+* Format env variable names for table display
+*/
+function formatEnvNames(env) {
+	if (!env) return "-";
+	if (Array.isArray(env)) return env.map((e) => `\`${e}\``).join(", ");
+	return `\`${env}\``;
 }
 /**
 * Render options as markdown table
@@ -105,14 +195,13 @@ function renderOptionsTable(info) {
 		lines.push("|--------|-------|-------------|----------|---------|");
 	}
 	for (const opt of info.options) {
-		const placeholder = opt.placeholder ?? opt.cliName.toUpperCase().replace(/-/g, "_");
-		const optionName = opt.type === "boolean" ? `\`--${opt.cliName}\`` : `\`--${opt.cliName} <${placeholder}>\``;
+		const optionName = formatOptionName(opt);
 		const alias = opt.alias ? `\`-${opt.alias}\`` : "-";
 		const desc = escapeTableCell$2(opt.description ?? "");
 		const required = opt.required ? "Yes" : "No";
 		const defaultVal = formatDefaultValue$1(opt.defaultValue);
 		if (hasEnv) {
-			const envNames = opt.env ? Array.isArray(opt.env) ? opt.env.map((e) => `\`${e}\``).join(", ") : `\`${opt.env}\`` : "-";
+			const envNames = formatEnvNames(opt.env);
 			lines.push(`| ${optionName} | ${alias} | ${desc} | ${required} | ${defaultVal} | ${envNames} |`);
 		} else lines.push(`| ${optionName} | ${alias} | ${desc} | ${required} | ${defaultVal} |`);
 	}
@@ -199,14 +288,13 @@ function renderOptionsTableFromArray(options) {
 		lines.push("|--------|-------|-------------|----------|---------|");
 	}
 	for (const opt of options) {
-		const placeholder = opt.placeholder ?? opt.cliName.toUpperCase().replace(/-/g, "_");
-		const optionName = opt.type === "boolean" ? `\`--${opt.cliName}\`` : `\`--${opt.cliName} <${placeholder}>\``;
+		const optionName = formatOptionName(opt);
 		const alias = opt.alias ? `\`-${opt.alias}\`` : "-";
 		const desc = escapeTableCell$2(opt.description ?? "");
 		const required = opt.required ? "Yes" : "No";
 		const defaultVal = formatDefaultValue$1(opt.defaultValue);
 		if (hasEnv) {
-			const envNames = opt.env ? Array.isArray(opt.env) ? opt.env.map((e) => `\`${e}\``).join(", ") : `\`${opt.env}\`` : "-";
+			const envNames = formatEnvNames(opt.env);
 			lines.push(`| ${optionName} | ${alias} | ${desc} | ${required} | ${defaultVal} | ${envNames} |`);
 		} else lines.push(`| ${optionName} | ${alias} | ${desc} | ${required} | ${defaultVal} |`);
 	}
@@ -322,17 +410,23 @@ function renderExamplesDefault(examples, results, opts) {
 	return lines.join("\n");
 }
 /**
+* Wrap content with section markers
+*/
+function wrapWithMarker(type, scope, content) {
+	return `${sectionStartMarker(type, scope)}\n${content}\n${sectionEndMarker(type, scope)}`;
+}
+/**
 * Create command renderer with options
 */
 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;
 	return (info) => {
-		const lines = [];
+		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;
-		lines.push(`${h} ${title}`);
-		lines.push("");
+		sections.push(wrapWithMarker("heading", scope, `${h} ${title}`));
 		if (info.description) {
 			const context = {
 				content: info.description,
@@ -340,10 +434,7 @@ function createCommandRenderer(options = {}) {
 				info
 			};
 			const content = customRenderDescription ? customRenderDescription(context) : context.content;
-			if (content) {
-				lines.push(content);
-				lines.push("");
-			}
+			if (content) sections.push(wrapWithMarker("description", scope, content));
 		}
 		{
 			const context = {
@@ -352,10 +443,7 @@ function createCommandRenderer(options = {}) {
 				info
 			};
 			const content = customRenderUsage ? customRenderUsage(context) : context.content;
-			if (content) {
-				lines.push(content);
-				lines.push("");
-			}
+			if (content) sections.push(wrapWithMarker("usage", scope, content));
 		}
 		if (info.positionalArgs.length > 0) {
 			const renderArgs = (args, opts) => {
@@ -371,10 +459,7 @@ function createCommandRenderer(options = {}) {
 				info
 			};
 			const content = customRenderArguments ? customRenderArguments(context) : renderArgs(context.args);
-			if (content) {
-				lines.push(content);
-				lines.push("");
-			}
+			if (content) sections.push(wrapWithMarker("arguments", scope, content));
 		}
 		if (info.options.length > 0) {
 			const renderOpts = (opts, renderOpts) => {
@@ -390,10 +475,7 @@ function createCommandRenderer(options = {}) {
 				info
 			};
 			const content = customRenderOptions ? customRenderOptions(context) : renderOpts(context.options);
-			if (content) {
-				lines.push(content);
-				lines.push("");
-			}
+			if (content) sections.push(wrapWithMarker("options", scope, content));
 		}
 		if (info.subCommands.length > 0) {
 			const effectiveAnchors = generateAnchors && includeSubcommandDetails;
@@ -410,10 +492,7 @@ function createCommandRenderer(options = {}) {
 				info
 			};
 			const content = customRenderSubcommands ? customRenderSubcommands(context) : renderSubs(context.subcommands);
-			if (content) {
-				lines.push(content);
-				lines.push("");
-			}
+			if (content) sections.push(wrapWithMarker("subcommands", scope, content));
 		}
 		if (info.examples && info.examples.length > 0) {
 			const renderEx = (examples, results, opts) => {
@@ -432,10 +511,7 @@ function createCommandRenderer(options = {}) {
 				info
 			};
 			const content = customRenderExamples ? customRenderExamples(context) : renderEx(context.examples, context.results);
-			if (content) {
-				lines.push(content);
-				lines.push("");
-			}
+			if (content) sections.push(wrapWithMarker("examples", scope, content));
 		}
 		if (info.notes) {
 			const context = {
@@ -444,10 +520,7 @@ function createCommandRenderer(options = {}) {
 				info
 			};
 			const content = customRenderNotes ? customRenderNotes(context) : context.content;
-			if (content) {
-				lines.push(content);
-				lines.push("");
-			}
+			if (content) sections.push(wrapWithMarker("notes", scope, content));
 		}
 		{
 			const context = {
@@ -456,14 +529,9 @@ function createCommandRenderer(options = {}) {
 				info
 			};
 			const content = customRenderFooter ? customRenderFooter(context) : context.content;
-			if (content) {
-				lines.push(content);
-				lines.push("");
-			}
+			if (content) sections.push(content);
 		}
-		while (lines.length > 0 && lines[lines.length - 1] === "") lines.pop();
-		lines.push("");
-		return lines.join("\n");
+		return sections.join("\n\n") + "\n";
 	};
 }
 /**
@@ -936,64 +1004,6 @@ async function renderCommandIndex(command, categories, options) {
 	return sections.join("\n\n");
 }
 
-//#endregion
-//#region src/docs/types.ts
-/**
-* Environment variable name for update mode
-*/
-const UPDATE_GOLDEN_ENV = "POLITTY_DOCS_UPDATE";
-/**
-* Marker prefix for command sections in generated documentation
-* Format: <!-- politty:command:<path>:start --> ... <!-- politty:command:<path>:end -->
-*/
-const COMMAND_MARKER_PREFIX = "politty:command";
-/**
-* Generate start marker for a command section
-*/
-function commandStartMarker(commandPath) {
-	return `<!-- ${COMMAND_MARKER_PREFIX}:${commandPath}:start -->`;
-}
-/**
-* Generate end marker for a command section
-*/
-function commandEndMarker(commandPath) {
-	return `<!-- ${COMMAND_MARKER_PREFIX}:${commandPath}:end -->`;
-}
-/**
-* Marker prefix for global options sections in generated documentation
-* Format: <!-- politty:global-options:start --> ... <!-- politty:global-options:end -->
-*/
-const GLOBAL_OPTIONS_MARKER_PREFIX = "politty:global-options";
-/**
-* Generate start marker for a global options section
-*/
-function globalOptionsStartMarker() {
-	return `<!-- ${GLOBAL_OPTIONS_MARKER_PREFIX}:start -->`;
-}
-/**
-* Generate end marker for a global options section
-*/
-function globalOptionsEndMarker() {
-	return `<!-- ${GLOBAL_OPTIONS_MARKER_PREFIX}:end -->`;
-}
-/**
-* Marker prefix for index sections in generated documentation
-* Format: <!-- politty:index:start --> ... <!-- politty:index:end -->
-*/
-const INDEX_MARKER_PREFIX = "politty:index";
-/**
-* Generate start marker for an index section
-*/
-function indexStartMarker() {
-	return `<!-- ${INDEX_MARKER_PREFIX}:start -->`;
-}
-/**
-* Generate end marker for an index section
-*/
-function indexEndMarker() {
-	return `<!-- ${INDEX_MARKER_PREFIX}:end -->`;
-}
-
 //#endregion
 //#region src/docs/golden-test.ts
 /**
@@ -1084,16 +1094,8 @@ function matchesIgnorePattern(path, ignorePattern) {
 */
 function expandCommandPaths(commandPaths, allCommands) {
 	const expanded = /* @__PURE__ */ new Set();
-	for (const cmdPath of commandPaths) if (containsWildcard(cmdPath)) {
-		const matches = expandWildcardPattern(cmdPath, allCommands);
-		for (const match of matches) {
-			expanded.add(match);
-			for (const path of allCommands.keys()) if (isSubcommandOf(path, match)) expanded.add(path);
-		}
-	} else {
-		if (allCommands.has(cmdPath)) expanded.add(cmdPath);
-		for (const path of allCommands.keys()) if (isSubcommandOf(path, cmdPath)) expanded.add(path);
-	}
+	const resolved = commandPaths.flatMap((cmdPath) => containsWildcard(cmdPath) ? expandWildcardPattern(cmdPath, allCommands) : [cmdPath]);
+	for (const cmdPath of resolved) for (const existingPath of allCommands.keys()) if (isSubcommandOf(existingPath, cmdPath)) expanded.add(existingPath);
 	return Array.from(expanded);
 }
 /**
@@ -1236,55 +1238,52 @@ function processFileHeader(existingContent, fileConfig, updateMode) {
 		wasUpdated: true
 	};
 }
+function formatCommandPath(commandPath) {
+	return commandPath === "" ? "<root>" : commandPath;
+}
 /**
-* Extract a command section from content using markers
-* Returns the content between start and end markers (including markers)
+* Extract a section marker's content from document content.
+* Returns the content between start and end markers (including markers).
 */
-function extractCommandSection(content, commandPath) {
-	const startMarker = commandStartMarker(commandPath);
-	const endMarker = commandEndMarker(commandPath);
-	const startIndex = content.indexOf(startMarker);
-	if (startIndex === -1) return null;
-	const endIndex = content.indexOf(endMarker, startIndex);
-	if (endIndex === -1) return null;
-	return content.slice(startIndex, endIndex + endMarker.length);
+function extractSectionMarker(content, type, scope) {
+	return extractMarkerSection(content, sectionStartMarker(type, scope), sectionEndMarker(type, scope));
 }
 /**
-* Collect command paths from command start markers in content.
+* Replace a section marker's content in document content.
+* Returns updated content, or null if marker not found.
 */
-function collectCommandMarkerPaths(content) {
-	const markerPattern = /<!--\s*politty:command:(.*?):start\s*-->/g;
-	const paths = [];
-	for (const match of content.matchAll(markerPattern)) paths.push(match[1] ?? "");
-	return paths;
+function replaceSectionMarker(content, type, scope, newContent) {
+	return replaceMarkerSection(content, sectionStartMarker(type, scope), sectionEndMarker(type, scope), newContent);
 }
-function formatCommandPath(commandPath) {
-	return commandPath === "" ? "<root>" : commandPath;
+/**
+* Collect all section types that have markers for a given command path.
+*/
+function collectSectionMarkers(content, commandPath) {
+	const found = [];
+	for (const type of SECTION_TYPES) if (extractSectionMarker(content, type, commandPath) !== null) found.push(type);
+	return found;
 }
 /**
-* Replace a command section in content using markers
-* Returns the updated content with the new section
+* Collect all command paths that have any section markers in the content.
 */
-function replaceCommandSection(content, commandPath, newSection) {
-	const startMarker = commandStartMarker(commandPath);
-	const endMarker = commandEndMarker(commandPath);
-	const startIndex = content.indexOf(startMarker);
-	if (startIndex === -1) return null;
-	const endIndex = content.indexOf(endMarker, startIndex);
-	if (endIndex === -1) return null;
-	return content.slice(0, startIndex) + newSection + content.slice(endIndex + endMarker.length);
+function collectSectionMarkerPaths(content) {
+	const sectionTypes = SECTION_TYPES.join("|");
+	const markerPattern = new RegExp(`<!--\\s*politty:command:(.*?):(?:${sectionTypes}):start\\s*-->`, "g");
+	const paths = /* @__PURE__ */ new Set();
+	for (const match of content.matchAll(markerPattern)) paths.add(match[1] ?? "");
+	return Array.from(paths);
 }
 /**
-* Insert a command section at the correct position based on specified order
-* Returns the updated content with the section inserted at the right position
+* Insert command section markers at the correct position based on specified order.
+* Uses the heading marker of adjacent commands as reference points.
 */
-function insertCommandSection(content, commandPath, newSection, specifiedOrder) {
+function insertCommandSections(content, commandPath, newSection, specifiedOrder) {
 	const targetIndex = specifiedOrder.indexOf(commandPath);
 	if (targetIndex === -1) return content.trimEnd() + "\n\n" + newSection + "\n";
 	for (let i = targetIndex + 1; i < specifiedOrder.length; i++) {
 		const nextCmd = specifiedOrder[i];
 		if (nextCmd === void 0) continue;
-		const nextMarker = commandStartMarker(nextCmd);
+		const nextMarker = sectionStartMarker("heading", nextCmd);
 		const nextIndex = content.indexOf(nextMarker);
 		if (nextIndex !== -1) {
 			let insertPos = nextIndex;
@@ -1296,11 +1295,15 @@ function insertCommandSection(content, commandPath, newSection, specifiedOrder)
 	for (let i = targetIndex - 1; i >= 0; i--) {
 		const prevCmd = specifiedOrder[i];
 		if (prevCmd === void 0) continue;
-		const prevEndMarker = commandEndMarker(prevCmd);
-		const prevEndIndex = content.indexOf(prevEndMarker);
-		if (prevEndIndex !== -1) {
-			const insertPos = prevEndIndex + prevEndMarker.length;
-			return content.slice(0, insertPos) + "\n" + newSection + content.slice(insertPos);
+		const prevMarkers = collectSectionMarkers(content, prevCmd);
+		if (prevMarkers.length > 0) {
+			const lastType = prevMarkers[prevMarkers.length - 1];
+			const prevEndMarker = sectionEndMarker(lastType, prevCmd);
+			const prevEndIndex = content.indexOf(prevEndMarker);
+			if (prevEndIndex !== -1) {
+				const insertPos = prevEndIndex + prevEndMarker.length;
+				return content.slice(0, insertPos) + "\n" + newSection + content.slice(insertPos);
+			}
 		}
 	}
 	return content.trimEnd() + "\n" + newSection + "\n";
@@ -1451,9 +1454,9 @@ function generateGlobalOptionsSection(config) {
 /**
 * Generate index section content with markers
 */
-async function generateIndexSection(categories, command, options) {
-	const startMarker = indexStartMarker();
-	const endMarker = indexEndMarker();
+async function generateIndexSection(categories, command, scope, options) {
+	const startMarker = indexStartMarker(scope);
+	const endMarker = indexEndMarker(scope);
 	return [
 		startMarker,
 		await renderCommandIndex(command, categories, options),
@@ -1514,13 +1517,13 @@ async function processGlobalOptionsMarker(existingContent, globalOptionsConfig,
 * Returns result with updated content and any diffs.
 * If the marker is not present in the file, the section is silently skipped.
 */
-async function processIndexMarker(existingContent, categories, command, updateMode, formatter, indexOptions) {
+async function processIndexMarker(existingContent, categories, command, scope, updateMode, formatter, indexOptions) {
 	let content = existingContent;
 	const diffs = [];
 	let hasError = false;
 	let wasUpdated = false;
-	const startMarker = indexStartMarker();
-	const endMarker = indexEndMarker();
+	const startMarker = indexStartMarker(scope);
+	const endMarker = indexEndMarker(scope);
 	const hasStartMarker = content.includes(startMarker);
 	const hasEndMarker = content.includes(endMarker);
 	if (!hasStartMarker && !hasEndMarker) return {
@@ -1550,7 +1553,7 @@ async function processIndexMarker(existingContent, categories, command, updateMo
 			wasUpdated
 		};
 	}
-	const generatedSection = await applyFormatter(await generateIndexSection(categories, command, indexOptions), formatter);
+	const generatedSection = await applyFormatter(await generateIndexSection(categories, command, scope, indexOptions), formatter);
 	if (existingSection !== generatedSection) if (updateMode) {
 		const updated = replaceMarkerSection(content, startMarker, endMarker, generatedSection);
 		if (updated) {
@@ -1598,21 +1601,16 @@ function findTargetCommandsInFile(targetCommands, filePath, files, allCommands,
 	return Array.from(expandedTargets);
 }
 /**
-* Generate a single command section with markers
+* Generate a single command section (already contains section markers from renderer)
 */
 function generateCommandSection(cmdPath, allCommands, render, filePath, fileMap) {
 	const info = allCommands.get(cmdPath);
 	if (!info) return null;
-	const renderedSection = render({
+	return render({
 		...info,
 		filePath,
 		fileMap
 	});
-	return [
-		commandStartMarker(cmdPath),
-		renderedSection,
-		commandEndMarker(cmdPath)
-	].join("\n");
 }
 /**
 * Generate markdown for a file containing multiple commands
@@ -1701,12 +1699,13 @@ async function generateDoc(config) {
 			for (const targetCommand of fileTargetCommands) {
 				const rawSection = generateCommandSection(targetCommand, allCommands, render, filePath, fileMap);
 				if (!rawSection) throw new Error(`Target command "${targetCommand}" not found in commands`);
-				const header = targetCommand === "" && fileConfig ? generateFileHeader(fileConfig) : null;
-				const generatedSection = await applyFormatter(header ? `${header}\n${rawSection}` : rawSection, formatter);
+				const generatedSection = await applyFormatter(rawSection, formatter);
 				if (!existingContent) {
 					if (updateMode) {
-						writeFile(filePath, generatedSection);
-						existingContent = generatedSection;
+						const header = targetCommand === "" && fileConfig ? generateFileHeader(fileConfig) : null;
+						const fullContent = header ? `${header}\n${generatedSection}` : generatedSection;
+						writeFile(filePath, fullContent);
+						existingContent = fullContent;
 						fileStatus = "created";
 					} else {
 						hasError = true;
@@ -1715,32 +1714,35 @@ async function generateDoc(config) {
 					}
 					continue;
 				}
-				const existingSection = extractCommandSection(existingContent, targetCommand);
-				const generatedSectionOnly = extractCommandSection(generatedSection, targetCommand);
-				if (!generatedSectionOnly) throw new Error(`Generated content does not contain section for command "${targetCommand}"`);
-				if (!existingSection) {
+				const existingMarkers = collectSectionMarkers(existingContent, targetCommand);
+				if (existingMarkers.length === 0) {
 					if (updateMode) {
-						existingContent = insertCommandSection(existingContent, targetCommand, generatedSectionOnly, specifiedCommands);
+						existingContent = insertCommandSections(existingContent, targetCommand, generatedSection, specifiedCommands);
 						writeFile(filePath, existingContent);
 						if (fileStatus !== "created") fileStatus = "updated";
 					} else {
 						hasError = true;
 						fileStatus = "diff";
-						diffs.push(`Existing file does not contain section for command "${targetCommand}"`);
+						diffs.push(`Existing file does not contain section markers for command "${targetCommand}"`);
 					}
 					continue;
 				}
-				if (existingSection !== generatedSectionOnly) if (updateMode) {
-					const updatedContent = replaceCommandSection(existingContent, targetCommand, generatedSectionOnly);
-					if (updatedContent) {
-						existingContent = updatedContent;
-						writeFile(filePath, existingContent);
-						if (fileStatus !== "created") fileStatus = "updated";
-					} else throw new Error(`Failed to replace section for command "${targetCommand}"`);
-				} else {
-					hasError = true;
-					fileStatus = "diff";
-					diffs.push(formatDiff(existingSection, generatedSectionOnly));
+				for (const sectionType of existingMarkers) {
+					const existingSection = extractSectionMarker(existingContent, sectionType, targetCommand);
+					const generatedSectionPart = extractSectionMarker(generatedSection, sectionType, targetCommand);
+					if (!existingSection || !generatedSectionPart) continue;
+					if (existingSection !== generatedSectionPart) if (updateMode) {
+						const updated = replaceSectionMarker(existingContent, sectionType, targetCommand, generatedSectionPart);
+						if (updated) {
+							existingContent = updated;
+							writeFile(filePath, existingContent);
+							if (fileStatus !== "created") fileStatus = "updated";
+						} else throw new Error(`Failed to replace ${sectionType} section for command "${targetCommand}"`);
+					} else {
+						hasError = true;
+						fileStatus = "diff";
+						diffs.push(formatDiff(existingSection, generatedSectionPart));
+					}
 				}
 			}
 		} else {
@@ -1782,10 +1784,10 @@ async function generateDoc(config) {
 			if (headerResult.diff) rootDocDiffs.push(headerResult.diff);
 			if (headerResult.hasError) hasError = true;
 			if (headerResult.wasUpdated) markerUpdated = true;
-			const unexpectedCommandMarkers = Array.from(new Set(collectCommandMarkerPaths(content)));
-			if (unexpectedCommandMarkers.length > 0) {
+			const unexpectedSectionPaths = Array.from(new Set(collectSectionMarkerPaths(content)));
+			if (unexpectedSectionPaths.length > 0) {
 				hasError = true;
-				rootDocDiffs.push(`Found unexpected command marker sections in rootDoc: ${unexpectedCommandMarkers.map((commandPath) => `"${formatCommandPath(commandPath)}"`).join(", ")}.`);
+				rootDocDiffs.push(`Found unexpected section markers in rootDoc: ${unexpectedSectionPaths.map((commandPath) => `"${formatCommandPath(commandPath)}"`).join(", ")}.`);
 			}
 			const normalizedGlobalOptions = normalizeGlobalOptions(rootDoc.globalOptions);
 			if (normalizedGlobalOptions) {
@@ -1796,7 +1798,8 @@ async function generateDoc(config) {
 				if (globalOptionsResult.wasUpdated) markerUpdated = true;
 			}
 			const derivedCategories = deriveIndexFromFiles(files, rootDocFilePath, allCommands, ignores);
-			const indexResult = await processIndexMarker(content, derivedCategories, command, updateMode, formatter, rootDoc.index);
+			const indexScope = node_path.relative(process.cwd(), rootDocFilePath);
+			const indexResult = await processIndexMarker(content, derivedCategories, command, indexScope, updateMode, formatter, rootDoc.index);
 			content = indexResult.content;
 			rootDocDiffs.push(...indexResult.diffs);
 			if (indexResult.hasError) hasError = true;
@@ -1848,15 +1851,14 @@ function initDocFile(config, fileSystem) {
 }
 
 //#endregion
-exports.COMMAND_MARKER_PREFIX = COMMAND_MARKER_PREFIX;
 exports.GLOBAL_OPTIONS_MARKER_PREFIX = GLOBAL_OPTIONS_MARKER_PREFIX;
 exports.INDEX_MARKER_PREFIX = INDEX_MARKER_PREFIX;
+exports.SECTION_MARKER_PREFIX = SECTION_MARKER_PREFIX;
+exports.SECTION_TYPES = SECTION_TYPES;
 exports.UPDATE_GOLDEN_ENV = UPDATE_GOLDEN_ENV;
 exports.assertDocMatch = assertDocMatch;
 exports.buildCommandInfo = buildCommandInfo;
 exports.collectAllCommands = collectAllCommands;
-exports.commandEndMarker = commandEndMarker;
-exports.commandStartMarker = commandStartMarker;
 exports.compareWithExisting = compareWithExisting;
 exports.createCommandRenderer = createCommandRenderer;
 exports.defaultRenderers = defaultRenderers;
@@ -1883,5 +1885,7 @@ exports.renderSubcommandsTable = renderSubcommandsTable;
 exports.renderSubcommandsTableFromArray = renderSubcommandsTableFromArray;
 exports.renderUsage = renderUsage;
 exports.resolveLazyCommand = require_subcommand_router.resolveLazyCommand;
+exports.sectionEndMarker = sectionEndMarker;
+exports.sectionStartMarker = sectionStartMarker;
 exports.writeFile = writeFile;
 //# sourceMappingURL=index.cjs.map