mdat 3.5.0 → 3.6.1

package/dist/bin/cli.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { S as version, a as expand, b as setLogger$1, d as templates_default, f as ensureArray, l as createReadme, r as collapse, s as strip, t as check, u as createReadmeInteractive, x as name, y as log } from "../lib-D3Djaa1D.js";
+import { S as version, a as expand, b as setLogger$1, d as templates_default, f as ensureArray, l as createReadme, r as collapse, s as strip, t as check, u as createReadmeInteractive, x as name, y as log } from "../lib-BU0oLDpf.js";
 import { createLogger } from "lognow";
 import picocolors from "picocolors";
 import prettyMilliseconds from "pretty-ms";

package/dist/lib/index.d.ts

@@ -179,6 +179,7 @@ declare const readmeMetadataTemplate: import("metascope").Template<{
   licenseFilePath: string | undefined;
   licenseUrl: string | undefined;
   name: string | undefined;
+  obsidianPluginId: string | undefined;
   operatingSystem: string[] | undefined;
   peerDependencies: {
     name: string;
@@ -186,9 +187,11 @@ declare const readmeMetadataTemplate: import("metascope").Template<{
     version: string;
   }[] | undefined;
   projectDirectory: string | undefined;
+  repositoryDirectory: string | undefined;
   repositoryUrl: string | undefined;
   runtimePlatform: string[] | undefined;
   usesGitLfs: boolean;
+  vscodeExtensionId: string | undefined;
 }>;
 type ReadmeMetadata = ReturnType<typeof readmeMetadataTemplate>;
 /**
@@ -225,6 +228,7 @@ export declare function getReadmeMetadata(): Promise<{
   licenseFilePath: string | undefined;
   licenseUrl: string | undefined;
   name: string | undefined;
+  obsidianPluginId: string | undefined;
   operatingSystem: string[] | undefined;
   peerDependencies: {
     name: string;
@@ -232,9 +236,11 @@ export declare function getReadmeMetadata(): Promise<{
     version: string;
   }[] | undefined;
   projectDirectory: string | undefined;
+  repositoryDirectory: string | undefined;
   repositoryUrl: string | undefined;
   runtimePlatform: string[] | undefined;
   usesGitLfs: boolean;
+  vscodeExtensionId: string | undefined;
 }>;
 /**
  * Reset all cached metadata. Call between tests or when the underlying project

package/dist/lib/index.js

@@ -1,3 +1,3 @@
-import { _ as getReadmeMetadata, a as expand, b as setLogger, c as stripString, g as getContextMetadata, h as mergeConfig, i as collapseString, l as createReadme, m as loadConfig, n as checkString, o as expandString, p as defineConfig, r as collapse, s as strip, t as check, u as createReadmeInteractive, v as resetMetadataCaches } from "../lib-D3Djaa1D.js";
+import { _ as getReadmeMetadata, a as expand, b as setLogger, c as stripString, g as getContextMetadata, h as mergeConfig, i as collapseString, l as createReadme, m as loadConfig, n as checkString, o as expandString, p as defineConfig, r as collapse, s as strip, t as check, u as createReadmeInteractive, v as resetMetadataCaches } from "../lib-BU0oLDpf.js";
 
 export { check, checkString, collapse, collapseString, createReadme as create, createReadmeInteractive as createInteractive, defineConfig, expand, expandString, getContextMetadata, getReadmeMetadata, loadConfig, mergeConfig, resetMetadataCaches, setLogger, strip, stripString };

package/dist/{lib-D3Djaa1D.js → lib-BU0oLDpf.js}

@@ -26,14 +26,13 @@ import { confirm, group, intro, note, outro, select } from "@clack/prompts";
 
 //#region package.json
 var name = "mdat";
-var version = "3.5.0";
+var version = "3.6.1";
 
 //#endregion
 //#region src/lib/deep-merge-defined.ts
 const deepmerge = deepmergeCustom({ mergeArrays: false });
 function stripUndefinedDeep(object) {
-	if (Array.isArray(object)) return object.map((v) => v !== null && typeof v === "object" ? stripUndefinedDeep(v) : v).filter((v) => v !== void 0);
-	return Object.entries(object).map(([k, v]) => [k, v !== null && typeof v === "object" ? stripUndefinedDeep(v) : v]).reduce((acc, [k, v]) => v === void 0 ? acc : {
+	return Array.isArray(object) ? object.map((v) => v !== null && typeof v === "object" ? stripUndefinedDeep(v) : v).filter((v) => v !== void 0) : Object.entries(object).map(([k, v]) => [k, v !== null && typeof v === "object" ? stripUndefinedDeep(v) : v]).reduce((acc, [k, v]) => v === void 0 ? acc : {
 		...acc,
 		[k]: v
 	}, {});
@@ -193,6 +192,29 @@ function getHomebrewFormula(packageName, scripts) {
 	}
 }
 /**
+* VS Code Marketplace item identifier for packages that are VS Code extensions,
+* identified by an `engines.vscode` field.
+*
+* @returns E.g. `kitschpatrol.tldraw-preview`, or undefined if the package
+*   isn't an extension
+*/
+function getVscodeExtensionId(nodePackage) {
+	return typeof nodePackage?.publisher === "string" && nodePackage.engines?.vscode !== void 0 ? `${nodePackage.publisher}.${nodePackage.name}` : void 0;
+}
+/**
+* Obsidian community plugin identifier, from the plugin's manifest.json.
+*/
+function getObsidianPluginId(manifests) {
+	return helpers.firstOf(manifests)?.data.id;
+}
+/**
+* Package location within a monorepo, from the package.json
+* `repository.directory` field.
+*/
+function getRepositoryDirectory(nodePackage) {
+	return typeof nodePackage?.repository === "object" ? nodePackage.repository.directory : void 0;
+}
+/**
 * Reset cached context metadata. Call between tests or when the underlying
 * project files may have changed on disk.
 *
@@ -202,12 +224,12 @@ function resetContextMetadata() {
 	metascopeMetadata = void 0;
 }
 const readmeMetadataTemplate = defineTemplate((context) => {
-	const { githubActions, gitStats, licenseFile, metascope, nodePackageJson } = context;
+	const { githubActions, gitStats, licenseFile, metascope, nodePackageJson, obsidianPluginManifestJson } = context;
 	const codemeta = templates.codemetaJson(context, {});
 	const nodePackage = helpers.firstOf(nodePackageJson)?.data;
 	const licenseFileData = helpers.firstOf(licenseFile);
 	const ciActionFilePath = helpers.ensureArray(githubActions).find((entry) => entry.data.name.toLowerCase() === "ci")?.source;
-	const repoUrl = codemeta.codeRepository?.replace(GIT_PREFIX_REGEX, "").replace(GIT_SUFFIX_REGEX, "").replace(TRAILING_SLASH_REGEX, "");
+	const repositoryUrl = codemeta.codeRepository?.replace(GIT_PREFIX_REGEX, "").replace(GIT_SUFFIX_REGEX, "").replace(TRAILING_SLASH_REGEX, "");
 	const bin = (() => {
 		if (nodePackage === void 0) return;
 		const binField = nodePackage.bin;
@@ -257,6 +279,9 @@ const readmeMetadataTemplate = defineTemplate((context) => {
 		};
 	})();
 	const homebrewFormula = getHomebrewFormula(nodePackage?.name, nodePackage?.scripts);
+	const repositoryDirectory = getRepositoryDirectory(nodePackage);
+	const vscodeExtensionId = getVscodeExtensionId(nodePackage);
+	const obsidianPluginId = getObsidianPluginId(obsidianPluginManifestJson);
 	const firstAuthor = helpers.firstOf(helpers.ensureArray(codemeta.author));
 	return {
 		author: helpers.firstOf(helpers.mixedStringsToArray(helpers.toBasicNames(codemeta.author))),
@@ -276,12 +301,15 @@ const readmeMetadataTemplate = defineTemplate((context) => {
 		licenseFilePath: licenseFileData?.source,
 		licenseUrl: licenseFileData?.data.match?.spdxUrl,
 		name: codemeta.name,
+		obsidianPluginId,
 		operatingSystem: codemeta.operatingSystem ?? getSupportedOperatingSystems(nodePackage?.os),
 		peerDependencies,
 		projectDirectory: metascope?.data.options.path === void 0 ? void 0 : `file://${metascope.data.options.path}`,
-		repositoryUrl: repoUrl,
+		repositoryDirectory,
+		repositoryUrl,
 		runtimePlatform: codemeta.runtimePlatform,
-		usesGitLfs: helpers.firstOf(gitStats)?.data.hasLfs === true
+		usesGitLfs: helpers.firstOf(gitStats)?.data.hasLfs === true,
+		vscodeExtensionId
 	};
 });
 let readmeMetadata;
@@ -316,24 +344,159 @@ function resetMetadataCaches() {
 
 //#endregion
 //#region src/lib/readme/rules/badges.ts
+const HOMEBREW_FORMULA_REGEX = /^(?<owner>[^\/]+)\/(?<tap>[^\/]+)\/(?<formula>[^\/]+)$/v;
+const GITHUB_REPOSITORY_REGEX$1 = /^https:\/\/github\.com\/(?<owner>[^\/]+)\/(?<repo>[^\/]+)$/v;
+const NO_NPM_PACKAGE = "no public npm package was found. Remove \"private\": true from package.json if the package is published, or list packages explicitly, e.g. badges({ npm: [\"package-name\"] })";
+const optionsSchema$2 = z.object({
+	bundleSize: z.boolean().optional(),
+	ci: z.boolean().optional(),
+	custom: z.record(z.string(), z.object({
+		image: z.string(),
+		link: z.string()
+	})).default({}),
+	githubRelease: z.boolean().optional(),
+	gitLfs: z.boolean().optional(),
+	homebrew: z.union([z.boolean(), z.string().regex(HOMEBREW_FORMULA_REGEX, "The badges \"homebrew\" option expects a formula in the form \"owner/tap/formula\"")]).optional(),
+	license: z.boolean().optional(),
+	npm: z.union([z.boolean(), z.array(z.string()).min(1, "Pass npm: false instead of an empty array to hide the NPM version badge")]).optional(),
+	npmDownloads: z.boolean().optional(),
+	obsidianDownloads: z.boolean().optional(),
+	vscode: z.boolean().optional()
+});
+/**
+* Escape text for a path segment of a shields.io static badge, where `-` and
+* `_` are delimiters and must be doubled to appear literally.
+*/
+function escapeStaticBadgeText(text) {
+	return encodeURIComponent(text.replaceAll("-", "--").replaceAll("_", "__"));
+}
+/**
+* One badge per npm package, for badges that report on npm packages.
+*/
+function mapNpmPackages(npmPackages, toBadge) {
+	return npmPackages.length === 0 ? { unavailable: NO_NPM_PACKAGE } : npmPackages.map((packageName) => toBadge(packageName));
+}
+/**
+* Owner and name of the project's GitHub repository, or undefined if the
+* repository isn't on GitHub.
+*/
+function getGithubRepository(repositoryUrl = "") {
+	const { owner, repo } = GITHUB_REPOSITORY_REGEX$1.exec(repositoryUrl)?.groups ?? {};
+	return owner === void 0 || repo === void 0 ? void 0 : {
+		owner,
+		repo
+	};
+}
+/**
+* Reason for badges that need a GitHub repository.
+*/
+function getNotGithubReason(repositoryUrl) {
+	return `${repositoryUrl === void 0 ? "no repository URL was found in the project metadata" : `the repository URL "${repositoryUrl}" is not a GitHub repository`}. Set the "repository" field in package.json to the project's GitHub repository.`;
+}
+/**
+* Explicit package names are useful for monorepos. Otherwise the package itself
+* is used if it's public, even when the NPM version badge is hidden, so the
+* download and size badges can still appear.
+*/
+function getNpmPackages(option, { isPublicNpmPackage, name }) {
+	if (Array.isArray(option)) return option;
+	return isPublicNpmPackage && name !== void 0 ? [name] : [];
+}
+/**
+* Badges in display order. Each appears when its metadata is available unless
+* it's `optIn`, and its option can hide it (`false`) or require it (`true`).
+*/
+const badgeDefinitions = [
+	{
+		key: "npm",
+		render: ({ npmPackages }) => mapNpmPackages(npmPackages, (packageName) => `[![NPM Package ${packageName}](https://img.shields.io/npm/v/${packageName}.svg)](https://www.npmjs.com/package/${packageName})`)
+	},
+	{
+		key: "license",
+		render: ({ license, licenseUrl }) => license === void 0 || licenseUrl === void 0 ? { unavailable: "no license file matching a known SPDX license was found" } : [`[![License: ${license}](https://img.shields.io/badge/License-${license.replaceAll("-", "--")}-yellow.svg)](${licenseUrl})`]
+	},
+	{
+		key: "ci",
+		render({ ciActionFileName, repositoryUrl }) {
+			if (ciActionFileName === void 0) return { unavailable: "no GitHub Actions workflow named \"CI\" was found in .github/workflows" };
+			if (repositoryUrl === void 0) return { unavailable: "no repository URL was found in the project metadata" };
+			return [`[![CI](${repositoryUrl}/actions/workflows/${ciActionFileName}/badge.svg)](${repositoryUrl}/actions/workflows/${ciActionFileName})`];
+		}
+	},
+	{
+		key: "gitLfs",
+		render: ({ usesGitLfs }) => usesGitLfs ? ["![Git LFS](https://img.shields.io/badge/Git%20LFS-enabled-F64935?logo=gitlfs&logoColor=white)"] : { unavailable: "the repository does not track any files with Git LFS" }
+	},
+	{
+		key: "vscode",
+		render({ repositoryDirectory, repositoryUrl, vscodeExtensionId }) {
+			if (vscodeExtensionId === void 0) return { unavailable: "package.json is missing a \"publisher\" or \"engines.vscode\" field" };
+			const repository = getGithubRepository(repositoryUrl);
+			if (repository === void 0) return { unavailable: `the extension version is read from package.json on GitHub, but ${getNotGithubReason(repositoryUrl)}` };
+			const packageJsonPath = [repositoryDirectory, "package.json"].filter((segment) => segment !== void 0).join("/");
+			const packageJsonUrl = `https://raw.githubusercontent.com/${repository.owner}/${repository.repo}/HEAD/${packageJsonPath}`;
+			return [`[![Visual Studio Marketplace Version](https://img.shields.io/badge/dynamic/json?url=${encodeURIComponent(packageJsonUrl)}&query=version&label=VS%20Code%20Marketplace)](https://marketplace.visualstudio.com/items?itemName=${vscodeExtensionId})`];
+		}
+	},
+	{
+		key: "homebrew",
+		render({ homebrewFormula, options }) {
+			const formulaPath = typeof options.homebrew === "string" ? options.homebrew : homebrewFormula;
+			if (formulaPath === void 0) return { unavailable: "no \"brewpub --tap <owner>/<tap>\" invocation was found in the package.json scripts. Pass the formula explicitly instead, e.g. badges({ homebrew: \"owner/tap/formula\" })" };
+			const formulaParts = HOMEBREW_FORMULA_REGEX.exec(formulaPath)?.groups;
+			if (formulaParts?.owner === void 0 || formulaParts.tap === void 0 || formulaParts.formula === void 0) return { unavailable: `the detected formula "${formulaPath}" is not in the form "owner/tap/formula"` };
+			const { formula, owner, tap } = formulaParts;
+			return [`[![Homebrew](https://img.shields.io/badge/Homebrew-${escapeStaticBadgeText(formulaPath)}-FBB040?logo=homebrew&logoColor=white)](https://github.com/${owner}/homebrew-${tap}/blob/HEAD/Formula/${formula}.rb)`];
+		}
+	},
+	{
+		key: "githubRelease",
+		optIn: true,
+		render({ repositoryUrl }) {
+			const repository = getGithubRepository(repositoryUrl);
+			if (repository === void 0) return { unavailable: getNotGithubReason(repositoryUrl) };
+			const { owner, repo } = repository;
+			return [`[![GitHub Release](https://img.shields.io/github/v/release/${owner}/${repo}?label=Release)](https://github.com/${owner}/${repo}/releases/latest)`];
+		}
+	},
+	{
+		key: "npmDownloads",
+		optIn: true,
+		render: ({ npmPackages }) => mapNpmPackages(npmPackages, (packageName) => `[![NPM Downloads ${packageName}](https://img.shields.io/npm/dm/${packageName})](https://www.npmjs.com/package/${packageName})`)
+	},
+	{
+		key: "obsidianDownloads",
+		optIn: true,
+		render({ obsidianPluginId }) {
+			if (obsidianPluginId === void 0) return { unavailable: "no Obsidian plugin manifest.json was found" };
+			const statsUrl = "https://raw.githubusercontent.com/obsidianmd/obsidian-releases/master/community-plugin-stats.json";
+			const query = `$["${obsidianPluginId}"].downloads`;
+			return [`[![Obsidian Downloads](https://img.shields.io/badge/dynamic/json?logo=obsidian&color=%23A88BFA&label=Downloads&query=${encodeURIComponent(query)}&url=${encodeURIComponent(statsUrl)})](https://community.obsidian.md/plugins/${obsidianPluginId})`];
+		}
+	},
+	{
+		key: "bundleSize",
+		optIn: true,
+		render: ({ npmPackages }) => mapNpmPackages(npmPackages, (packageName) => `[![Bundle Size ${packageName}](https://img.shields.io/bundlephobia/minzip/${packageName}?label=Size)](https://bundlephobia.com/package/${packageName})`)
+	}
+];
 var badges_default = { badges: { async content(options) {
-	const validOptions = z.object({
-		custom: z.record(z.string(), z.object({
-			image: z.string(),
-			link: z.string()
-		})).optional(),
-		npm: z.array(z.string()).optional()
-	}).optional().parse(options);
+	const validOptions = optionsSchema$2.parse(options ?? {});
 	const metadata = await getReadmeMetadata();
-	const { ciActionFileName, license, licenseUrl, name, repositoryUrl, usesGitLfs } = metadata;
+	const context = {
+		...metadata,
+		npmPackages: getNpmPackages(validOptions.npm, metadata),
+		options: validOptions
+	};
 	const badges = [];
-	if (validOptions?.npm === void 0) {
-		if (metadata.isPublicNpmPackage) badges.push(`[![NPM Package ${name}](https://img.shields.io/npm/v/${name}.svg)](https://www.npmjs.com/package/${name})`);
-	} else for (const packageName of validOptions.npm) badges.push(`[![NPM Package ${packageName}](https://img.shields.io/npm/v/${packageName}.svg)](https://www.npmjs.com/package/${packageName})`);
-	if (license !== void 0 && licenseUrl !== void 0) badges.push(`[![License: ${license}](https://img.shields.io/badge/License-${license.replaceAll("-", "--")}-yellow.svg)](${licenseUrl})`);
-	if (ciActionFileName !== void 0 && repositoryUrl !== void 0) badges.push(`[![CI](${repositoryUrl}/actions/workflows/${ciActionFileName}/badge.svg)](${repositoryUrl}/actions/workflows/${ciActionFileName})`);
-	if (usesGitLfs) badges.push("![Git LFS](https://img.shields.io/badge/Git%20LFS-enabled-F64935?logo=gitlfs&logoColor=white)");
-	if (validOptions?.custom !== void 0) for (const [badgeName, { image, link }] of Object.entries(validOptions.custom)) badges.push(`[![${badgeName}](${image})](${link})`);
+	for (const { key, optIn = false, render } of badgeDefinitions) {
+		const option = validOptions[key];
+		if (option === false || optIn && option === void 0) continue;
+		const result = render(context);
+		if (Array.isArray(result)) badges.push(...result);
+		else if (option !== void 0) throw new Error(`The "${key}" badge was requested, but ${result.unavailable}`);
+	}
+	for (const [badgeName, { image, link }] of Object.entries(validOptions.custom)) badges.push(`[![${badgeName}](${image})](${link})`);
 	return badges.join("\n");
 } } };
 
@@ -418,29 +581,51 @@ var code_default = { code: { async content(options) {
 
 //#endregion
 //#region src/lib/readme/rules/utilities/heading.ts
+const MAX_HEADING_LEVEL = 6;
 /**
 * Option schema for the Markdown heading level (1-6) at which a rule emits its
-* section heading. Sub-headings, if any, are nested one level deeper. Rules
-* default to level 3, matching their placement under a level 2 section like
-* "Getting started" in the house readme template.
+* section heading. Sub-headings, if any, are nested one level deeper, whether
+* or not the section heading itself is shown. Each rule's default matches its
+* placement in the house readme template.
 */
-const headingLevelSchema = z.number().int().min(1).max(6).optional();
+const headingLevelSchema = z.number().int().min(1).max(MAX_HEADING_LEVEL).optional();
+/**
+* Option schema for a rule's section heading. `true` (the default) emits the
+* rule's standard heading, `false` leaves the heading out, and a string
+* replaces the heading text.
+*/
+const headingSchema = z.union([z.boolean(), z.string().trim().min(1)]).optional();
 /**
 * The `#` prefix for a Markdown heading, clamped to the maximum level of 6.
 */
 function getHeadingPrefix(level) {
-	return "#".repeat(Math.min(level, 6));
+	return "#".repeat(Math.min(level, MAX_HEADING_LEVEL));
+}
+/**
+* The lines of a rule's section heading, including the blank line separating it
+* from the section body, or no lines if the heading is suppressed.
+*
+* @param heading - Value of the rule's `heading` option
+* @param level - Markdown heading level
+* @param defaultText - Heading text used unless `heading` overrides it
+*/
+function getHeadingLines(heading, level, defaultText) {
+	if (heading === false) return [];
+	const text = typeof heading === "string" ? heading : defaultText;
+	return [`${getHeadingPrefix(level)} ${text}`, ""];
 }
 
 //#endregion
 //#region src/lib/readme/rules/contributing.ts
 var contributing_default = { contributing: { async content(options) {
-	const validOptions = z.object({ headingLevel: headingLevelSchema }).optional().parse(options);
+	const validOptions = z.object({
+		heading: headingSchema,
+		headingLevel: headingLevelSchema
+	}).optional().parse(options);
 	const { issuesUrl } = await getReadmeMetadata();
 	if (issuesUrl === void 0) throw new Error("Could not find \"bugs.url\" entry in package.json");
 	return [
-		`${getHeadingPrefix(validOptions?.headingLevel ?? 2)} Contributing`,
-		"",
+		...getHeadingLines(validOptions?.heading, validOptions?.headingLevel ?? 2, "Contributing"),
 		`[Issues](${issuesUrl}) are welcome and appreciated.`,
 		"",
 		"Please open an issue to discuss changes before submitting a pull request. Unsolicited PRs (especially AI-generated ones) are unlikely to be merged.",
@@ -530,7 +715,10 @@ function getPlatformItem(key, version) {
 	return version === void 0 || version.trim() === "" ? `- ${display}` : `- ${display} ${describeVersionRange(version)}`;
 }
 var dependencies_default = { dependencies: { async content(options) {
-	const validOptions = z.object({ headingLevel: headingLevelSchema }).optional().parse(options);
+	const validOptions = z.object({
+		heading: headingSchema,
+		headingLevel: headingLevelSchema
+	}).optional().parse(options);
 	const { engines, operatingSystem, peerDependencies, runtimePlatform } = await getReadmeMetadata();
 	const items = [];
 	const engineEntries = Object.entries(engines ?? {});
@@ -551,11 +739,7 @@ var dependencies_default = { dependencies: { async content(options) {
 		items.push(`- [${name}](${npmUrl}) \`${version}\` _(peer dependency)_`);
 	}
 	if (items.length === 0) return "";
-	return [
-		`${getHeadingPrefix(validOptions?.headingLevel ?? 3)} Dependencies`,
-		"",
-		...items
-	].join("\n");
+	return [...getHeadingLines(validOptions?.heading, validOptions?.headingLevel ?? 3, "Dependencies"), ...items].join("\n");
 } } };
 
 //#endregion
@@ -598,7 +782,10 @@ const TOOL_INFO = {
 	}
 };
 var development_dependencies_default = { "development-dependencies": { async content(options) {
-	const validOptions = z.object({ headingLevel: headingLevelSchema }).optional().parse(options);
+	const validOptions = z.object({
+		heading: headingSchema,
+		headingLevel: headingLevelSchema
+	}).optional().parse(options);
 	const { developmentDependencies } = await getReadmeMetadata();
 	if (developmentDependencies === void 0) return "";
 	const { packageManagers, runtimes } = developmentDependencies;
@@ -608,11 +795,7 @@ var development_dependencies_default = { "development-dependencies": { async con
 		const display = info ? `[${info.display}](${info.url})` : name;
 		items.push(version === void 0 || version === "" ? `- ${display}` : `- ${display} ${version}`);
 	}
-	return [
-		`${getHeadingPrefix(validOptions?.headingLevel ?? 3)} Development dependencies`,
-		"",
-		...items
-	].join("\n");
+	return [...getHeadingLines(validOptions?.heading, validOptions?.headingLevel ?? 3, "Development dependencies"), ...items].join("\n");
 } } };
 
 //#endregion
@@ -625,12 +808,15 @@ var dev_dependencies_default = { "dev-dependencies": getSoleRule(development_dep
 //#endregion
 //#region src/lib/readme/rules/license.ts
 var license_default = { license: { async content(options) {
-	const validOptions = z.object({ headingLevel: headingLevelSchema }).optional().parse(options);
+	const validOptions = z.object({
+		heading: headingSchema,
+		headingLevel: headingLevelSchema
+	}).optional().parse(options);
 	const { author, authorUrl, license, licenseFilePath } = await getReadmeMetadata();
 	if (author === void 0) throw new Error("Could not find author name in project");
 	if (license === void 0 || licenseFilePath === void 0) throw new Error("Could not find license for project");
 	const authorDisplay = authorUrl === void 0 ? author : `[${author}](${authorUrl})`;
-	return `${`${getHeadingPrefix(validOptions?.headingLevel ?? 2)} License`}\n[${license}](${licenseFilePath}) © ${authorDisplay}`;
+	return [...getHeadingLines(validOptions?.heading, validOptions?.headingLevel ?? 2, "License"), `[${license}](${licenseFilePath}) © ${authorDisplay}`].join("\n");
 } } };
 
 //#endregion
@@ -732,23 +918,23 @@ function getLibraryLines(name, bin, hasTypes, dev) {
 var install_default = { install: { async content(options) {
 	const validOptions = z.object({
 		dev: z.boolean().optional(),
+		heading: headingSchema,
 		headingLevel: headingLevelSchema,
 		homebrew: z.union([z.string(), z.literal(false)]).optional()
-	}).optional().parse(options);
+	}).parse(options ?? {});
 	const { bin, hasTypes, homebrewFormula, isLibrary, isNodePackage, isPublicNpmPackage, name, runtimePlatform } = await getReadmeMetadata();
 	if (name === void 0) throw new Error("Could not find project name");
-	const headingLevel = validOptions?.headingLevel ?? 3;
-	const heading = `${getHeadingPrefix(headingLevel)} Installation`;
+	const headingLevel = validOptions.headingLevel ?? 3;
+	const headingLines = getHeadingLines(validOptions.heading, headingLevel, "Installation");
 	const subheading = getHeadingPrefix(headingLevel + 1);
 	if (isNodePackage) {
 		if (!isPublicNpmPackage) throw new Error("Install instructions require a publishable package, but package.json sets \"private\": true");
-		const homebrew = validOptions?.homebrew === void 0 ? homebrewFormula : validOptions.homebrew === false ? void 0 : validOptions.homebrew;
+		const homebrew = validOptions.homebrew === void 0 ? homebrewFormula : validOptions.homebrew === false ? void 0 : validOptions.homebrew;
 		const hasCli = bin !== void 0 && bin.length > 0;
 		const cliLines = getCliLines(name, homebrew);
-		const libraryLines = getLibraryLines(name, bin, hasTypes, validOptions?.dev ?? false);
+		const libraryLines = getLibraryLines(name, bin, hasTypes, validOptions.dev ?? false);
 		if (hasCli && isLibrary) return [
-			heading,
-			"",
+			...headingLines,
 			`There are several ways to install ${name} depending on how you're planning to use it:`,
 			"",
 			`${subheading} CLI`,
@@ -759,20 +945,12 @@ var install_default = { install: { async content(options) {
 			"",
 			...libraryLines
 		].join("\n");
-		return [
-			heading,
-			"",
-			...hasCli ? cliLines : libraryLines
-		].join("\n");
+		return [...headingLines, ...hasCli ? cliLines : libraryLines].join("\n");
 	}
 	const platform = (prefix) => runtimePlatform?.some((p) => p.startsWith(prefix));
 	const command = platform("python") ? `pip install ${name}` : platform("rust") ? `cargo install ${name}` : platform("go") ? `go install ${name}@latest` : platform("ruby") ? `gem install ${name}` : void 0;
 	if (command === void 0) throw new Error("Could not determine project ecosystem for install instructions");
-	return [
-		heading,
-		"",
-		...codeBlock$1(command)
-	].join("\n");
+	return [...headingLines, ...codeBlock$1(command)].join("\n");
 } } };
 
 //#endregion
@@ -913,6 +1091,7 @@ const SKILLS_DIRECTORY = "skills";
 const SKILL_FILE_NAME = "SKILL.md";
 const GITHUB_REPOSITORY_REGEX = /^https:\/\/github\.com\/(?<slug>[^\/]+\/[^\/]+)$/v;
 const WHITESPACE_REGEX = /\s+/gv;
+const FIRST_SENTENCE_REGEX = /^.*?(?<!\b(?:e\.g|i\.e|vs))[.!?](?=\s+\p{Lu})/v;
 const skillFrontmatterSchema = z.object({
 	description: z.string().trim().min(1),
 	name: z.string().trim().min(1)
@@ -951,11 +1130,12 @@ async function findSkills(projectDirectory) {
 			if (error instanceof Error && "code" in error && error.code === "ENOENT") continue;
 			throw error;
 		}
+		const filePath = `${SKILLS_DIRECTORY}/${entry.name}/${SKILL_FILE_NAME}`;
 		const frontmatter = skillFrontmatterSchema.safeParse(matter(skillFile).data);
-		if (!frontmatter.success) throw new Error(`Skill at "${path.relative(projectDirectory, skillFilePath)}" needs "name" and "description" strings in its frontmatter`);
+		if (!frontmatter.success) throw new Error(`Skill at "${filePath}" needs "name" and "description" strings in its frontmatter`);
 		skills.push({
 			...frontmatter.data,
-			filePath: `${SKILLS_DIRECTORY}/${entry.name}/${SKILL_FILE_NAME}`
+			filePath
 		});
 	}
 	return skills.toSorted((a, b) => a.name.localeCompare(b.name));
@@ -964,58 +1144,66 @@ async function findSkills(projectDirectory) {
 * The argument identifying a repository to the `skills add` command, which
 * accepts an `owner/repo` shorthand for GitHub and full URLs for other hosts.
 */
-function getSkillsCliSource(repoUrl) {
-	return GITHUB_REPOSITORY_REGEX.exec(repoUrl)?.groups?.slug ?? repoUrl;
+function getSkillsCliSource(repositoryUrl) {
+	return GITHUB_REPOSITORY_REGEX.exec(repositoryUrl)?.groups?.slug ?? repositoryUrl;
+}
+/**
+* The first sentence of a skill description, which by convention says what the
+* skill does, leaving out the guidance on when to use it that follows.
+*/
+function getFirstSentence(description) {
+	const singleLine = description.replaceAll(WHITESPACE_REGEX, " ");
+	return FIRST_SENTENCE_REGEX.exec(singleLine)?.[0] ?? singleLine;
 }
 var skills_default = { skills: { async content(options) {
-	const validOptions = z.object({ headingLevel: headingLevelSchema }).optional().parse(options);
+	const validOptions = z.object({
+		heading: headingSchema,
+		headingLevel: headingLevelSchema
+	}).optional().parse(options);
 	const skills = await findSkills(process.cwd());
 	if (skills.length === 0) throw new Error(`Could not find any skills, expected at least one "${SKILLS_DIRECTORY}/<name>/${SKILL_FILE_NAME}" file in the project`);
 	const { isPublicNpmPackage, name, repositoryUrl } = await getReadmeMetadata();
 	if (name === void 0) throw new Error("Could not find project name");
 	const headingLevel = validOptions?.headingLevel ?? 2;
-	const subheading = getHeadingPrefix(headingLevel + 1);
-	const skillNoun = skills.length === 1 ? "skill" : "skills";
-	const skillPronoun = skills.length === 1 ? "it" : "them";
-	const introLines = [
-		`${getHeadingPrefix(headingLevel)} Agent skills`,
+	const skillHeading = getHeadingPrefix(headingLevel + 1);
+	const skillNoun = plur("skill", skills.length);
+	const agentSkillsLink = `${skills.length === 1 ? "an" : skills.length} [${plur("Agent Skill", skills.length)}](https://agentskills.io)`;
+	const skillsCliLink = "Vercel's [skills CLI](https://github.com/vercel-labs/skills)";
+	const headingLines = getHeadingLines(validOptions?.heading, headingLevel, "Agent skills");
+	const skillLines = [`Included ${skillNoun}:`, ...skills.flatMap((skill) => [
 		"",
-		`This project includes ${skills.length === 1 ? "an [Agent Skill](https://agentskills.io)" : "[Agent Skills](https://agentskills.io)"} that ${skills.length === 1 ? "teaches" : "teach"} coding agents like Claude Code and Codex how to work with ${name}:`,
+		`${skillHeading} Skill: [\`${skill.name}\`](${skill.filePath})`,
 		"",
-		...skills.map((skill) => `- **[\`${skill.name}\`](${skill.filePath})**: ${skill.description.replaceAll(WHITESPACE_REGEX, " ")}`)
-	];
+		getFirstSentence(skill.description)
+	])];
 	if (!isPublicNpmPackage) {
 		if (repositoryUrl === void 0) throw new Error("Skill install instructions require either a publishable npm package or a repository URL in the project metadata");
 		return [
-			...introLines,
+			...headingLines,
+			`This project includes ${agentSkillsLink} to help coding agents work with ${name}.`,
+			"",
+			`To install the ${skillNoun}, run ${skillsCliLink}:`,
 			"",
-			`Install ${skillPronoun} from the repository with the [\`skills\`](https://github.com/vercel-labs/skills) CLI:`,
+			...codeBlock(`npx skills add ${getSkillsCliSource(repositoryUrl)}`),
 			"",
-			...codeBlock(`npx skills add ${getSkillsCliSource(repositoryUrl)}`)
+			...skillLines
 		].join("\n");
 	}
 	return [
-		...introLines,
+		...headingLines,
+		`This project bundles ${agentSkillsLink} in its published package to help coding agents work with ${name}.`,
 		"",
-		`The ${skillNoun} ${skills.length === 1 ? "is" : "are"} published in the \`${SKILLS_DIRECTORY}\` directory of the \`${name}\` package. Nothing is added to your project until you install ${skillPronoun} with one of the tools below.`,
-		"",
-		`${subheading} Sync from the installed package (recommended)`,
-		"",
-		`With \`${name}\` installed as a project dependency, the [\`skills\`](https://github.com/vercel-labs/skills) CLI finds skills bundled in your dependencies and copies them into your project's agent skill directories, so they match the version of \`${name}\` you have installed:`,
+		`To sync the ${skillNoun} into your project, run ${skillsCliLink} from your project root:`,
 		"",
 		...codeBlock("npx skills experimental_sync"),
-		"",
-		`Run the command again after upgrading \`${name}\` to refresh the copies. The \`experimental_sync\` command is experimental and its behavior may change.`,
 		...repositoryUrl === void 0 ? [] : [
 			"",
-			`${subheading} Install from the repository`,
+			"Or install globally:",
 			"",
-			`If \`${name}\` is not a dependency of your project, for example because you use a global installation, install the ${skillNoun} from the repository instead:`,
-			"",
-			...codeBlock(`npx skills add ${getSkillsCliSource(repositoryUrl)}`),
-			"",
-			`${skills.length === 1 ? "A skill" : "Skills"} installed this way ${skills.length === 1 ? "follows" : "follow"} the repository's default branch rather than your installed version of \`${name}\`.`
-		]
+			...codeBlock(`npx skills add ${getSkillsCliSource(repositoryUrl)} --global`)
+		],
+		"",
+		...skillLines
 	].join("\n");
 } } };
 
@@ -1032,6 +1220,7 @@ var table_of_contents_default = { "table-of-contents": {
 				z.literal(5),
 				z.literal(6)
 			]).optional(),
+			heading: headingSchema,
 			headingLevel: headingLevelSchema
 		}).optional().parse(options);
 		const result = toc(tree, {
@@ -1040,12 +1229,12 @@ var table_of_contents_default = { "table-of-contents": {
 			tight: true
 		});
 		if (result.map === void 0) throw new Error("Could not generate table of contents");
-		const heading = `${getHeadingPrefix(validOptions?.headingLevel ?? 2)} Table of contents`;
 		const rootWrapper = {
 			children: result.map.children,
 			type: "root"
 		};
-		return [heading, remark().use(remarkGfm).stringify(rootWrapper).replaceAll("\n\n", "\n")].join("\n");
+		const tocString = remark().use(remarkGfm).stringify(rootWrapper).replaceAll("\n\n", "\n");
+		return [...getHeadingLines(validOptions?.heading, validOptions?.headingLevel ?? 2, "Table of contents"), tocString].join("\n");
 	},
 	order: 1
 } };

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "mdat",
-  "version": "3.5.0",
-  "description": "CLI tool and TypeScript library implementing the Markdown Autophagic Template (MDAT) system. MDAT lets you use comments as dynamic content templates in Markdown files, making it easy to generate and update readme boilerplate.",
+  "version": "3.6.1",
+  "description": "CLI tool and TypeScript library to turn comments into content in Markdown files. MDAT makes it easy to generate and update dynamic boilerplate in project readmes.",
   "keywords": [
     "mdat",
     "markdown",
@@ -52,7 +52,7 @@
     "gray-matter-es": "^0.2.1",
     "lognow": "^0.8.4",
     "mdast-util-toc": "^7.1.0",
-    "metascope": "^0.12.0",
+    "metascope": "^0.12.1",
     "path-type": "^6.0.0",
     "picocolors": "^1.1.1",
     "plur": "^6.0.0",
@@ -71,7 +71,7 @@
   },
   "devDependencies": {
     "@arethetypeswrong/core": "^0.18.5",
-    "@kitschpatrol/shared-config": "^8.10.1",
+    "@kitschpatrol/shared-config": "^8.11.0",
     "@types/mdast": "^4.0.4",
     "@types/node": "~24.13.6",
     "@types/unist": "^3.0.3",
@@ -80,7 +80,7 @@
     "brewpub": "^0.4.0",
     "bumpp": "^12.3.0",
     "execa": "^10.0.1",
-    "mdat-plugin-cli-help": "^3.3.0",
+    "mdat-plugin-cli-help": "^3.4.0",
     "mdat-plugin-example": "^3.0.0",
     "mdat-plugin-tldraw": "^3.0.0",
     "nanoid": "^6.0.1",

package/readme.md

@@ -4,26 +4,19 @@
 
 <!-- /title -->
 
-<!-- badges({
-  custom: {
-    "Homebrew": {
-      image:
-        "https://img.shields.io/badge/Homebrew-kitschpatrol%2Ftap%2Fmdat-FBB040?logo=homebrew&logoColor=white",
-      link: "https://github.com/kitschpatrol/homebrew-tap/blob/main/Formula/mdat.rb",
-    },
-  }
-}) -->
+<!-- badges({ npmDownloads: true }) -->
 
 [![NPM Package mdat](https://img.shields.io/npm/v/mdat.svg)](https://www.npmjs.com/package/mdat)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/license/mit)
 [![CI](https://github.com/kitschpatrol/mdat/actions/workflows/ci.yml/badge.svg)](https://github.com/kitschpatrol/mdat/actions/workflows/ci.yml)
-[![Homebrew](https://img.shields.io/badge/Homebrew-kitschpatrol%2Ftap%2Fmdat-FBB040?logo=homebrew&logoColor=white)](https://github.com/kitschpatrol/homebrew-tap/blob/main/Formula/mdat.rb)
+[![Homebrew](https://img.shields.io/badge/Homebrew-kitschpatrol%2Ftap%2Fmdat-FBB040?logo=homebrew&logoColor=white)](https://github.com/kitschpatrol/homebrew-tap/blob/HEAD/Formula/mdat.rb)
+[![NPM Downloads mdat](https://img.shields.io/npm/dm/mdat)](https://www.npmjs.com/package/mdat)
 
 <!-- /badges -->
 
 <!-- description -->
 
-**CLI tool and TypeScript library implementing the Markdown Autophagic Template (MDAT) system. MDAT lets you use comments as dynamic content templates in Markdown files, making it easy to generate and update readme boilerplate.**
+**CLI tool and TypeScript library to turn comments into content in Markdown files. MDAT makes it easy to generate and update dynamic boilerplate in project readmes.**
 
 <!-- /description -->
 
@@ -47,8 +40,8 @@
   - [Creating a rule plugin](#creating-a-rule-plugin)
   - [Available rule plugins](#available-rule-plugins)
 - [Agent skills](#agent-skills)
-  - [Sync from the installed package (recommended)](#sync-from-the-installed-package-recommended)
-  - [Install from the repository](#install-from-the-repository)
+  - [Skill: `mdat`](#skill-mdat)
+  - [Skill: `mdat-plugin-authoring`](#skill-mdat-plugin-authoring)
 - [Migrating from 1.x to 2.x](#migrating-from-1x-to-2x)
   - [Flat CLI commands](#flat-cli-commands)
   - [Polyglot metadata](#polyglot-metadata)
@@ -74,9 +67,9 @@ MDAT is a CLI tool and library that uses HTML comments in Markdown files as plac
 <!-- tldraw({src: "assets/mdat-flow.tldr"}) -->
 
 <picture>
-  <source media="(prefers-color-scheme: dark)" srcset="assets/mdat-flow-63a3366c-dark.svg">
-  <source media="(prefers-color-scheme: light)" srcset="assets/mdat-flow-63a3366c-light.svg">
-  <img alt="tldraw diagram" src="assets/mdat-flow-63a3366c-light.svg">
+  <source media="(prefers-color-scheme: dark)" srcset="assets/mdat-flow-c037b16c-dark.svg">
+  <source media="(prefers-color-scheme: light)" srcset="assets/mdat-flow-c037b16c-light.svg">
+  <img alt="tldraw diagram" src="assets/mdat-flow-c037b16c-light.svg">
 </picture>
 
 <!-- /tldraw -->
@@ -250,7 +243,9 @@ npm install mdat
 
 <!-- cli-help -->
 
-#### Command: `mdat`
+#### Commands
+
+##### Command: `mdat`
 
 Work with MDAT placeholder comments in Markdown files.
 
@@ -274,7 +269,7 @@ mdat [command] [files..] [options]
 
 _See the sections below for more information on each subcommand._
 
-#### Subcommand: `mdat expand`
+##### Subcommand: `mdat expand`
 
 Expand MDAT placeholder comments. If no files are provided, the closest readme.md is expanded.
 
@@ -299,7 +294,7 @@ mdat expand [files..] [options]
 | `--help`<br>`-h`    | Show help                                                                                                                     | `boolean` |                                                     |
 | `--version`<br>`-v` | Show version number                                                                                                           | `boolean` |                                                     |
 
-#### Subcommand: `mdat collapse`
+##### Subcommand: `mdat collapse`
 
 Collapse MDAT placeholder comments. If no files are provided, the closest readme.md is collapsed.
 
@@ -323,7 +318,7 @@ mdat collapse [files..] [options]
 | `--help`<br>`-h`    | Show help                                                                                                                     | `boolean` |                                                     |
 | `--version`<br>`-v` | Show version number                                                                                                           | `boolean` |                                                     |
 
-#### Subcommand: `mdat strip`
+##### Subcommand: `mdat strip`
 
 Strip MDAT comments while preserving expanded content. If no files are provided, the closest readme.md is stripped.
 
@@ -347,7 +342,7 @@ mdat strip [files..] [options]
 | `--help`<br>`-h`    | Show help                                                                                                                     | `boolean` |                                                     |
 | `--version`<br>`-v` | Show version number                                                                                                           | `boolean` |                                                     |
 
-#### Subcommand: `mdat check`
+##### Subcommand: `mdat check`
 
 Check if MDAT placeholder comments are up to date. Exits with code 1 if any files have stale or unexpanded content.
 
@@ -369,7 +364,7 @@ mdat check [files..] [options]
 | `--help`<br>`-h`    | Show help                                                                                                                     | `boolean` |
 | `--version`<br>`-v` | Show version number                                                                                                           | `boolean` |
 
-#### Subcommand: `mdat create`
+##### Subcommand: `mdat create`
 
 Create a new Markdown file from a template.
 
@@ -592,7 +587,17 @@ See the [Examples section](https://github.com/kitschpatrol/remark-mdat#examples)
 
 ### Bundled rules
 
-Every rule that emits a section heading accepts a `headingLevel` option (`1`-`6`) to control the heading's Markdown level, with any sub-headings nested one level deeper. The defaults match each rule's placement in the bundled MDAT Readme template: `2` for top-level sections (`table-of-contents`, `contributing`, and `license`), and `3` for the rules that sit under "Getting started" (`dependencies`, `install`, and `development-dependencies`).
+Every stand-alone rule that generates a section of the readme emits its own heading, and accepts two options to control it:
+
+- `heading` is `true` by default, which emits the rule's standard heading. Pass a string to replace the heading text, or `false` to leave the heading out, e.g. when you've written your own heading above the comment, or when the same rule appears several times in one section.
+
+- `headingLevel` (`1`-`6`) sets the heading's Markdown level. Any sub-headings are nested one level deeper, whether or not the heading itself is shown. The defaults match each rule's placement in the bundled MDAT Readme template: `2` for top-level sections (`table-of-contents`, `contributing`, `license`, and `skills`), and `3` for the rules that sit under "Getting started" (`dependencies`, `install`, and `development-dependencies`).
+
+```md
+<!-- install({ heading: "Setup", headingLevel: 2 }) -->
+```
+
+Rules that generate inline content, like `badges`, `code`, and `size`, have no heading. Rule plugins follow the same convention.
 
 #### Stand-alone
 
@@ -606,7 +611,28 @@ Every rule that emits a section heading accepts a `headingLevel` option (`1`-`6`
 
 - ##### `<!-- badges -->`
 
-  Generates badges based on project metadata. Supports NPM version, license, CI status, and Git LFS badges.
+  Generates badges based on project metadata. Each badge has an option. Leave it out for the default behavior, pass `false` to hide the badge, or pass `true` to require it, which reports an error if the metadata the badge needs is missing. Two options also take a value that replaces the detected metadata.
+
+  | Option              | Badge                                                                                | Default                                                                 | Value                                           |
+  | ------------------- | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------- | ----------------------------------------------- |
+  | `npm`               | NPM version, for each package                                                        | Shown for public packages                                               | Package names (`string[]`), useful in monorepos |
+  | `license`           | License                                                                              | Shown when a license file matches a known SPDX license                  |                                                 |
+  | `ci`                | GitHub Actions CI status                                                             | Shown when a workflow is named "CI"                                     |                                                 |
+  | `gitLfs`            | Git LFS                                                                              | Shown when the repository tracks files with Git LFS                     |                                                 |
+  | `vscode`            | VS Code Marketplace version                                                          | Shown for VS Code extensions hosted on GitHub                           |                                                 |
+  | `homebrew`          | Homebrew tap                                                                         | Shown when a `brewpub --tap` invocation is found in the package scripts | Formula (`"owner/tap/formula"`)                 |
+  | `githubRelease`     | Latest GitHub release                                                                | Hidden                                                                  |                                                 |
+  | `npmDownloads`      | Monthly NPM downloads, for each package                                              | Hidden                                                                  |                                                 |
+  | `obsidianDownloads` | Obsidian community plugin downloads                                                  | Hidden                                                                  |                                                 |
+  | `bundleSize`        | [Bundlephobia](https://bundlephobia.com) minified and gzipped size, for each package | Hidden                                                                  |                                                 |
+
+  Badges appear in the order of the table, followed by `custom` badges, which take a `Record<string, { image: string, link: string }>` keyed by alt text.
+
+  The download and size badges cover the packages listed in `npm`, or the current package if it's public, even when `npm` is `false`. VS Code extensions are identified by the `publisher` and `engines.vscode` fields in `package.json`. Shields.io retired its Marketplace badge, so the version is read from `package.json` in the GitHub repository instead, respecting `repository.directory` in monorepos. The Homebrew formula is detected the same way as in the `install` rule. The GitHub release badge needs a GitHub repository URL, and the Obsidian downloads badge reads the plugin ID from `manifest.json`.
+
+  ```md
+  <!-- badges({ ci: false, npmDownloads: true }) -->
+  ```
 
 - ##### `<!-- description -->`
 
@@ -665,11 +691,11 @@ Every rule that emits a section heading accepts a `headingLevel` option (`1`-`6`
 
 - ##### `<!-- skills -->`
 
-  Documents the [Agent Skills](https://agentskills.io) bundled with the project and how to install them. Detects skills from `skills/<name>/SKILL.md` files, and lists each skill's name and description from its frontmatter, linking the name to the skill's `SKILL.md` file. Publishable npm packages get instructions for syncing skills from the installed package with the [`skills`](https://github.com/vercel-labs/skills) CLI's `experimental_sync` command (recommended), and for installing them from the repository with `skills add`. Private packages and non-Node projects only get the repository instructions. Reports an error if no skills are found. Remember to include the `skills` directory in the `files` field of `package.json`. The optional `headingLevel` sets the Markdown heading level and defaults to `2`.
+  Documents the [Agent Skills](https://agentskills.io) bundled with the project and how to install them. Detects skills from `skills/<name>/SKILL.md` files, and gives each one a "Skill:" sub-heading linking to its `SKILL.md` file, followed by the first sentence of the description from its frontmatter. Publishable npm packages get instructions for syncing skills from the installed package with the `experimental_sync` command of Vercel's [skills CLI](https://github.com/vercel-labs/skills), and for installing them from the repository with `skills add`. Private packages and non-Node projects only get the repository instructions. Reports an error if no skills are found. Remember to include the `skills` directory in the `files` field of `package.json`. The optional `headingLevel` sets the Markdown heading level and defaults to `2`.
 
 #### Compound
 
-Compound rules combine several stand-alone rules under a single keyword. Options are passed as an array with one entry per stand-alone rule, in order, e.g. `<!-- footer([{ headingLevel: 3 }, { headingLevel: 3 }]) -->`.
+Compound rules combine several stand-alone rules under a single keyword. Options are passed as an array with one entry per stand-alone rule, in order, e.g. `<!-- footer([{ headingLevel: 3 }, { heading: "Legal", headingLevel: 3 }]) -->`.
 
 - ##### `<!-- header -->`
 
@@ -767,44 +793,41 @@ Transform a CLI command's `--help` output into Markdown tables. Recursively call
 
 Example: `<!-- cli-help -->`
 
-#### [mdat-plugin-api](https://github.com/kitschpatrol/mdat-plugin-api)
+#### [mdat-plugin-api-help](https://github.com/kitschpatrol/mdat-plugin-api-help)
 
 Generate API documentation for a TypeScript package's public exports. Runs [TypeDoc](https://typedoc.org) over the package's entry point and embeds signatures, JSDoc descriptions, parameter and property tables, and examples as Markdown. A compact format renders one table row per export for large or namespaced APIs, and exports can be selected by name.
 
-Example: `<!-- api({ format: "compact", include: ["sync*"] }) -->`
+Example: `<!-- api-help({ format: "compact", include: ["sync*"] }) -->`
 
-<!-- //skills -->
+<!-- skills -->
 
 ## Agent skills
 
-This project includes [Agent Skills](https://agentskills.io) that teach coding agents like Claude Code and Codex how to work with mdat:
+This project bundles 2 [Agent Skills](https://agentskills.io) in its published package to help coding agents work with mdat.
 
-- **[`mdat`](skills/mdat/SKILL.md)**: Use and configure mdat, the Markdown Autophagic Template CLI and library that expands HTML comment placeholders such as `<!-- title -->` in Markdown files. Use when a readme or other Markdown file contains mdat comment placeholders, when editing mdat.config.ts or an "mdat" key in package.json, when generating or updating readme boilerplate from project metadata, when `mdat check` fails, or when calling the mdat TypeScript API.
-- **[`mdat-plugin-authoring`](skills/mdat-plugin-authoring/SKILL.md)**: Write custom mdat expansion rules and publishable mdat rule plugins (mdat-plugin-\* packages). Use when creating or debugging rule functions for mdat comment placeholders, validating comment arguments, reading project metadata or the Markdown tree inside a rule, building compound rules, or packaging and testing rules for reuse across projects.
+To sync the skills into your project, run Vercel's [skills CLI](https://github.com/vercel-labs/skills) from your project root:
 
-The skills are published in the `skills` directory of the `mdat` package. Nothing is added to your project until you install them with one of the tools below.
-
-### Sync from the installed package (recommended)
+```sh
+npx skills experimental_sync
+```
 
-With `mdat` installed as a project dependency, the [`skills`](https://github.com/vercel-labs/skills) CLI finds skills bundled in your dependencies and copies them into your project's agent skill directories, so they match the version of `mdat` you have installed:
+Or install globally:
 
 ```sh
-npx skills experimental_sync
+npx skills add kitschpatrol/mdat --global
 ```
 
-Run the command again after upgrading `mdat` to refresh the copies. The `experimental_sync` command is experimental and its behavior may change.
+Included skills:
 
-### Install from the repository
+### Skill: [`mdat`](skills/mdat/SKILL.md)
 
-If `mdat` is not a dependency of your project, for example because you use a global installation, install the skills from the repository instead:
+Use and configure mdat, the Markdown Autophagic Template CLI and library that expands HTML comment placeholders such as `<!-- title -->` in Markdown files.
 
-```sh
-npx skills add kitschpatrol/mdat
-```
+### Skill: [`mdat-plugin-authoring`](skills/mdat-plugin-authoring/SKILL.md)
 
-Skills installed this way follow the repository's default branch rather than your installed version of `mdat`.
+Write custom mdat expansion rules and publishable mdat rule plugins (mdat-plugin-\* packages).
 
-<!-- //skills -->
+<!-- /skills -->
 
 ## Migrating from 1.x to 2.x
 
@@ -906,6 +929,8 @@ There's quite a bit of prior art and similar explorations of this problem space:
 
 This project was split from a monorepo containing both `mdat` and `remark-mdat` into separate repos in July 2024.
 
+The name "MDAT" is an acronym for the "Markdown Autophagic Template" system, so named because of the circularity of a templating system where the input file is also the output file.
+
 Run `pnpm bench` to compare performance against `test/benchmarks/baseline.json`. Run `pnpm bench:baseline` to refresh the saved results using Vitest 5's benchmark format. Both commands support filters such as `-t loadConfig`; refreshing a filtered subset preserves the other baselines. Use the same machine and Node.js version for meaningful comparisons.
 
 ## Maintainers

package/skills/mdat/SKILL.md

@@ -61,24 +61,26 @@ Only JSON5 values are accepted. No JavaScript is evaluated. Bundled rules valida
 
 These work without any configuration. They read normalized project metadata, so most also work in Python, Rust, Go, and Ruby projects, not only Node.
 
-| Keyword                                               | Output                                                                            | Options                                                    |
-| ----------------------------------------------------- | --------------------------------------------------------------------------------- | ---------------------------------------------------------- |
-| `title`                                               | Project name as a heading.                                                        |                                                            |
-| `banner`                                              | A banner image found in the project directory.                                    |                                                            |
-| `badges`                                              | npm version, license, CI status, and Git LFS badges.                              | `npm: string[]`, `custom: { [name]: { image, link } }`     |
-| `description` (alias `short-description`)             | Project description.                                                              |                                                            |
-| `table-of-contents` (alias `toc`)                     | Table of contents from the document headings.                                     | `depth` (default `3`), `headingLevel` (default `2`)        |
-| `install` (alias `installation`)                      | Install instructions for consumers of the package. Private packages are rejected. | `headingLevel` (default `3`), `dev`, `homebrew`            |
-| `dependencies`                                        | Runtime platform requirements and required peer dependencies.                     | `headingLevel` (default `3`)                               |
-| `development-dependencies` (alias `dev-dependencies`) | Tools needed to work on the project, from `devEngines` and `packageManager`.      | `headingLevel` (default `3`)                               |
-| `contributing`                                        | Invitation to open issues and pull requests.                                      | `headingLevel` (default `2`)                               |
-| `license`                                             | License section.                                                                  | `headingLevel` (default `2`)                               |
-| `code`                                                | A code block embedded from a file.                                                | `file` (required), `language`, `trim` (default `true`)     |
-| `size`                                                | A file's size.                                                                    | `file` (required), `compression`: `none`, `gzip`, `brotli` |
-| `size-table`                                          | A table of file sizes with Gzip and Brotli columns.                               | `files` (required), `precision` (default `0`)              |
-| `skills`                                              | Agent Skills found in `skills/<name>/SKILL.md` and how to install them.           | `headingLevel` (default `2`)                               |
-| `header`                                              | Compound: `title`, `banner`, `badges`, `short-description`.                       | Array, one entry per sub-rule in order.                    |
-| `footer`                                              | Compound: `contributing`, `license`.                                              | Array, one entry per sub-rule in order.                    |
+Rules that generate a section emit their own heading. Their `heading` option is `true` by default, takes a string to replace the heading text, and takes `false` to leave the heading out, e.g. under a hand-written heading or when a rule appears several times in one section. `headingLevel` sets the heading's level, with sub-headings nested one level deeper whether or not the heading is shown.
+
+| Keyword                                               | Output                                                                                                                                                                            | Options                                                                                                                                                                                                                                                  |
+| ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `title`                                               | Project name as a heading.                                                                                                                                                        |                                                                                                                                                                                                                                                          |
+| `banner`                                              | A banner image found in the project directory.                                                                                                                                    |                                                                                                                                                                                                                                                          |
+| `badges`                                              | npm version, license, CI, Git LFS, VS Code Marketplace, and Homebrew badges when detected, plus opt-in GitHub release, npm downloads, Obsidian downloads, and bundle size badges. | `npm`, `license`, `ci`, `gitLfs`, `vscode`, `homebrew`, `githubRelease`, `npmDownloads`, `obsidianDownloads`, `bundleSize`: `false` hides, `true` requires. Also `npm: string[]`, `homebrew: "owner/tap/formula"`, `custom: { [name]: { image, link } }` |
+| `description` (alias `short-description`)             | Project description.                                                                                                                                                              |                                                                                                                                                                                                                                                          |
+| `table-of-contents` (alias `toc`)                     | Table of contents from the document headings.                                                                                                                                     | `depth` (default `3`), `heading`, `headingLevel` (default `2`)                                                                                                                                                                                           |
+| `install` (alias `installation`)                      | Install instructions for consumers of the package. Private packages are rejected.                                                                                                 | `heading`, `headingLevel` (default `3`), `dev`, `homebrew`                                                                                                                                                                                               |
+| `dependencies`                                        | Runtime platform requirements and required peer dependencies.                                                                                                                     | `heading`, `headingLevel` (default `3`)                                                                                                                                                                                                                  |
+| `development-dependencies` (alias `dev-dependencies`) | Tools needed to work on the project, from `devEngines` and `packageManager`.                                                                                                      | `heading`, `headingLevel` (default `3`)                                                                                                                                                                                                                  |
+| `contributing`                                        | Invitation to open issues and pull requests.                                                                                                                                      | `heading`, `headingLevel` (default `2`)                                                                                                                                                                                                                  |
+| `license`                                             | License section.                                                                                                                                                                  | `heading`, `headingLevel` (default `2`)                                                                                                                                                                                                                  |
+| `code`                                                | A code block embedded from a file.                                                                                                                                                | `file` (required), `language`, `trim` (default `true`)                                                                                                                                                                                                   |
+| `size`                                                | A file's size.                                                                                                                                                                    | `file` (required), `compression`: `none`, `gzip`, `brotli`                                                                                                                                                                                               |
+| `size-table`                                          | A table of file sizes with Gzip and Brotli columns.                                                                                                                               | `files` (required), `precision` (default `0`)                                                                                                                                                                                                            |
+| `skills`                                              | Agent Skills found in `skills/<name>/SKILL.md` and how to install them.                                                                                                           | `heading`, `headingLevel` (default `2`)                                                                                                                                                                                                                  |
+| `header`                                              | Compound: `title`, `banner`, `badges`, `short-description`.                                                                                                                       | Array, one entry per sub-rule in order.                                                                                                                                                                                                                  |
+| `footer`                                              | Compound: `contributing`, `license`.                                                                                                                                              | Array, one entry per sub-rule in order.                                                                                                                                                                                                                  |
 
 File paths in `code`, `size`, and `size-table` resolve from the current working directory.
 

package/skills/mdat-plugin-authoring/SKILL.md

@@ -101,6 +101,14 @@ const metadata = await getContextMetadata()
 
 See the exported `ReadmeMetadata` type for the complete field list. Call `resetMetadataCaches()` between tests that change project files on disk.
 
+## Headings
+
+Follow the convention of the bundled rules so that readmes stay consistent:
+
+- A rule that generates a section emits its own heading. A rule that generates inline content, like a badge or a code block, has no heading.
+- Accept a `heading` option. `true` is the default and emits the rule's standard heading, a string replaces the heading text, and `false` leaves the heading out.
+- Accept a `headingLevel` option (`1`-`6`) for the heading's level. Nest any sub-headings one level deeper, whether or not the heading is shown. Default to the level that suits the section's usual place in a readme.
+
 ## Order and compound rules
 
 - `order` defaults to `0`. Rules with a higher order run later. Use it when a rule reads content other rules generate. The bundled `table-of-contents` rule uses `order: 1` so that it sees headings produced by other rules.