@zebradil/docs-kit 0.0.0-stage → 0.11.0

package/packages/docs-kit/kit.test.mjs

@@ -0,0 +1,74 @@
+import assert from 'node:assert/strict';
+import { mkdtempSync, readdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { test } from 'node:test';
+import { fileURLToPath } from 'node:url';
+import docsKit from './index.mjs';
+import { minorVersions, selectVersions } from './versions.mjs';
+
+const path = (p) => fileURLToPath(new URL(p, import.meta.url));
+
+test('schema theme enum matches the shipped theme files', () => {
+  const schema = JSON.parse(readFileSync(path('../../schema/site.schema.json'), 'utf8'));
+  const themes = readdirSync(path('themes')).map((f) => f.replace(/\.css$/, ''));
+  assert.deepEqual(themes.sort(), schema.properties.theme.enum.sort());
+});
+
+test('serves the site at <owner>.github.io/<repo>', () => {
+  const config = docsKit({ site: path('../../examples/site.yaml') });
+  assert.equal(config.site, 'https://zebradil.github.io');
+  assert.equal(config.base, '/kasha');
+});
+
+test('serves the site at the root of a custom domain', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'docs-kit-'));
+  const site = join(dir, 'site.yaml');
+  writeFileSync(site, `${readFileSync(path('../../examples/site.yaml'), 'utf8')}\ndomain: kasha.dev\n`);
+  const config = docsKit({ site });
+  assert.equal(config.site, 'https://kasha.dev');
+  assert.equal(config.base, '/');
+});
+
+test('accepts analytics with data-* attributes only', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'docs-kit-'));
+  const site = join(dir, 'site.yaml');
+  const withAttribute = (attr) =>
+    `${readFileSync(path('../../examples/site.yaml'), 'utf8')}\nanalytics:\n  script: https://stats.example.dev/app.js\n  attributes:\n    ${attr}\n`;
+  writeFileSync(site, withAttribute('data-website-id: abc'));
+  assert.doesNotThrow(() => docsKit({ site }));
+  writeFileSync(site, withAttribute('onload: alert(1)'));
+  assert.throws(() => docsKit({ site }), /\/analytics\/attributes/);
+});
+
+test('rejects an invalid site.yaml with readable errors', () => {
+  assert.throws(() => docsKit({ site: path('../../schema/testdata/broken.yaml') }), /must be one of: default, mono, porridge/);
+});
+
+test('serves a release version below the site root', (t) => {
+  t.after(() => delete process.env.DOCS_KIT_VERSION);
+  process.env.DOCS_KIT_VERSION = 'v1.2';
+  const config = docsKit({ site: path('../../examples/site.yaml') });
+  assert.equal(config.base, '/kasha/v1.2');
+  process.env.DOCS_KIT_VERSION = '../x';
+  assert.throws(() => docsKit({ site: path('../../examples/site.yaml') }), /not a path segment/);
+});
+
+test('picks the newest patch of each minor version, newest minor first', () => {
+  const tags = ['v1.2.0', 'v1.10.0', 'v1.2.3', 'v1.2.10', 'v2.0.0-rc.1', 'v0.9.1', 'docs-v3.0.0', 'v1.10.1', ''];
+  assert.deepEqual(minorVersions(tags), [
+    { name: 'v1.10', tag: 'v1.10.1', line: '1' },
+    { name: 'v1.2', tag: 'v1.2.10', line: '1' },
+    { name: 'v0.9', tag: 'v0.9.1', line: '0.9' },
+  ]);
+});
+
+test('selects the newest minors, the newest minor of each newest major, and pinned ones', () => {
+  const tags = ['v3.0.0', 'v2.5.0', 'v2.4.0', 'v2.3.0', 'v1.9.0', 'v1.8.0', 'v0.4.0', 'v0.3.0'];
+  const names = (options) => selectVersions(minorVersions(tags), options).map((v) => v.name);
+  assert.deepEqual(names({ majors: 3, minors: 3 }), ['v3.0', 'v2.5', 'v2.4', 'v1.9']);
+  assert.deepEqual(names({ majors: 0, minors: 1, pin: ['v1.8', 'v9.9'] }), ['v3.0', 'v1.8']);
+  // Below 1.0 each minor is its own release line.
+  assert.deepEqual(names({ majors: 5, minors: 0 }), ['v3.0', 'v2.5', 'v1.9', 'v0.4', 'v0.3']);
+  assert.deepEqual(names({}), ['v3.0', 'v2.5', 'v2.4', 'v1.9']);
+});

package/packages/docs-kit/layout.css

@@ -0,0 +1,5 @@
+/* Layout tokens shared by every theme; loaded before the theme so a theme can still override them.
+   Starlight's 45rem default squeezes CLI reference tables and code blocks. */
+:root {
+  --sl-content-width: 55rem;
+}

package/packages/docs-kit/llms.txt.mjs

@@ -0,0 +1,31 @@
+import site from 'virtual:docs-kit/site';
+import { docsSections, pageMarkdown, siteRoot } from './page.md.mjs';
+
+/**
+ * Serves llms.txt (https://llmstxt.org): an index linking every page's Markdown, and llms-full.txt: every page in one
+ * file, for pasting a project's whole docs into a model's context.
+ */
+export function getStaticPaths() {
+  return [{ params: { name: 'llms' } }, { params: { name: 'llms-full' } }];
+}
+
+export async function GET(context) {
+  const sections = await docsSections();
+  const root = siteRoot(context);
+  const head = `# ${site.name}\n\n> ${site.tagline}`;
+
+  if (context.params.name === 'llms-full') {
+    const pages = sections.flatMap(({ pages }) => pages.map((page) => pageMarkdown(page, root)));
+    return new Response([`${head}\n`, ...pages].join('\n'));
+  }
+
+  const links = sections.map(
+    ({ label, pages }) =>
+      `## ${label}\n\n` +
+      pages
+        .map(({ id, data }) => `- [${data.title}](${new URL(`${id}.md`, root)})${data.description ? `: ${data.description}` : ''}`)
+        .join('\n'),
+  );
+  const intro = `Each page below links to its Markdown source. All pages in one file: ${new URL('llms-full.txt', root)}`;
+  return new Response([head, intro, ...links].join('\n\n') + '\n');
+}

package/packages/docs-kit/page.md.mjs

@@ -0,0 +1,42 @@
+import { getCollection } from 'astro:content';
+
+const sections = ['Getting started', 'Guides', 'Concepts', 'Reference'];
+
+/** Published docs pages in sidebar order, grouped under the sidebar's section labels. */
+export async function docsSections() {
+  const pages = (await getCollection('docs', ({ data }) => !data.draft)).sort(
+    (a, b) => (a.data.sidebar?.order ?? Infinity) - (b.data.sidebar?.order ?? Infinity) || a.id.localeCompare(b.id),
+  );
+  const section = ({ id }) => (id.includes('/') ? id.split('/')[0] : 'getting started');
+  return sections
+    .map((label) => ({ label, pages: pages.filter((page) => section(page) === label.toLowerCase()) }))
+    .filter(({ pages }) => pages.length);
+}
+
+/** The site's root URL, base path included, with a trailing slash. */
+export const siteRoot = ({ site }) => new URL(import.meta.env.BASE_URL.replace(/\/?$/, '/'), site);
+
+// Inline `](target)` and reference-style `[label]: target` link destinations.
+// shortcut: also matches look-alikes inside code blocks; parse with remark if a page trips on it.
+const linkTarget = /(\]\(|^ {0,3}\[[^\]]+\]:[ \t]*)([^)\s]+)/gm;
+
+/**
+ * A page as Markdown: its title and description from frontmatter, then the source body. Relative links are written
+ * against the page's HTML URL (/guides/x/), so they are made absolute to stay valid at /guides/x.md and in llms-full.txt.
+ */
+export function pageMarkdown({ id, data: { title, description }, body = '' }, root) {
+  const page = new URL(`${id}/`, root);
+  const absolute = body.trim().replace(linkTarget, (_, prefix, target) => prefix + new URL(target, page));
+  return [`# ${title}`, description && `> ${description}`, absolute].filter(Boolean).join('\n\n') + '\n';
+}
+
+/** Serves each docs page's Markdown at its URL with `.md` appended, for agents that read docs. */
+export async function getStaticPaths() {
+  return (await docsSections()).flatMap(({ pages }) => pages.map((entry) => ({ params: { slug: entry.id }, props: { entry } })));
+}
+
+export function GET(context) {
+  return new Response(pageMarkdown(context.props.entry, siteRoot(context)), {
+    headers: { 'Content-Type': 'text/markdown; charset=utf-8' },
+  });
+}

package/packages/docs-kit/text.mjs

@@ -0,0 +1,6 @@
+/** Escapes text for HTML strings passed to `set:html` or Starlight's hero slots. */
+export const escape = (text) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+
+// ponytail: only `inline code` is rendered; switch to a Markdown renderer if bodies need links or emphasis.
+/** Escapes text and renders its `inline code` spans. */
+export const inline = (text) => escape(text).replace(/`([^`]+)`/g, '<code>$1</code>');

package/packages/docs-kit/themes/default.css

@@ -0,0 +1,12 @@
+/* Starlight's stock palette and fonts with a teal accent. */
+:root {
+  --sl-color-accent-low: hsl(174, 60%, 16%);
+  --sl-color-accent: hsl(174, 70%, 40%);
+  --sl-color-accent-high: hsl(174, 70%, 82%);
+}
+
+:root[data-theme='light'] {
+  --sl-color-accent-low: hsl(174, 60%, 88%);
+  --sl-color-accent: hsl(174, 80%, 30%);
+  --sl-color-accent-high: hsl(174, 80%, 18%);
+}

package/packages/docs-kit/themes/mono.css

@@ -0,0 +1,30 @@
+/* Grayscale, monospace everywhere. */
+:root {
+  --sl-font: var(--sl-font-system-mono);
+  --sl-color-white: hsl(0, 0%, 100%);
+  --sl-color-gray-1: hsl(0, 0%, 92%);
+  --sl-color-gray-2: hsl(0, 0%, 76%);
+  --sl-color-gray-3: hsl(0, 0%, 56%);
+  --sl-color-gray-4: hsl(0, 0%, 36%);
+  --sl-color-gray-5: hsl(0, 0%, 22%);
+  --sl-color-gray-6: hsl(0, 0%, 12%);
+  --sl-color-black: hsl(0, 0%, 4%);
+  --sl-color-accent-low: hsl(0, 0%, 20%);
+  --sl-color-accent: hsl(0, 0%, 90%);
+  --sl-color-accent-high: hsl(0, 0%, 100%);
+}
+
+:root[data-theme='light'] {
+  --sl-color-white: hsl(0, 0%, 0%);
+  --sl-color-gray-1: hsl(0, 0%, 10%);
+  --sl-color-gray-2: hsl(0, 0%, 22%);
+  --sl-color-gray-3: hsl(0, 0%, 36%);
+  --sl-color-gray-4: hsl(0, 0%, 56%);
+  --sl-color-gray-5: hsl(0, 0%, 78%);
+  --sl-color-gray-6: hsl(0, 0%, 93%);
+  --sl-color-gray-7: hsl(0, 0%, 97%);
+  --sl-color-black: hsl(0, 0%, 100%);
+  --sl-color-accent-low: hsl(0, 0%, 88%);
+  --sl-color-accent: hsl(0, 0%, 15%);
+  --sl-color-accent-high: hsl(0, 0%, 0%);
+}

package/packages/docs-kit/themes/porridge.css

@@ -0,0 +1,42 @@
+/* Warm oat and roast neutrals with a honey accent; Fraunces headings over Instrument Sans. */
+@import '@fontsource-variable/fraunces';
+@import '@fontsource-variable/instrument-sans';
+@import '@fontsource-variable/jetbrains-mono';
+
+:root {
+  --sl-font: 'Instrument Sans Variable', system-ui, sans-serif;
+  --sl-font-mono: 'JetBrains Mono Variable', ui-monospace, monospace;
+  --kit-font-display: 'Fraunces Variable', Georgia, serif;
+
+  --sl-color-white: #f2eadb;
+  --sl-color-gray-1: #e5dac7;
+  --sl-color-gray-2: #c9b8a2;
+  --sl-color-gray-3: #a8957f;
+  --sl-color-gray-4: #6b5a4c;
+  --sl-color-gray-5: #3f3128;
+  --sl-color-gray-6: #211a15;
+  --sl-color-black: #17120e;
+  --sl-color-accent-low: #3a2a18;
+  --sl-color-accent: #e39a3b;
+  --sl-color-accent-high: #f6ce96;
+}
+
+:root[data-theme='light'] {
+  --sl-color-white: #1e1712;
+  --sl-color-gray-1: #2b2119;
+  --sl-color-gray-2: #4a3a2e;
+  --sl-color-gray-3: #6b5a4c;
+  --sl-color-gray-4: #9a8876;
+  --sl-color-gray-5: #cdb99a;
+  --sl-color-gray-6: #e5dac6;
+  --sl-color-gray-7: #efe7d8;
+  --sl-color-black: #f7f2e8;
+  --sl-color-accent-low: #f4ddbb;
+  --sl-color-accent: #8a4b1f;
+  --sl-color-accent-high: #4a2a16;
+}
+
+:is(h1, h2, h3, .site-title, .card .title) {
+  font-family: var(--kit-font-display);
+  letter-spacing: -0.015em;
+}

package/packages/docs-kit/themes/sieve.css

@@ -0,0 +1,49 @@
+/* Cool graphite with a signal-green accent and amber for "down"; Schibsted Grotesk over IBM Plex Mono. */
+@import '@fontsource-variable/schibsted-grotesk';
+@import '@fontsource/ibm-plex-mono/400.css';
+@import '@fontsource/ibm-plex-mono/500.css';
+
+:root {
+  --sl-font: 'Schibsted Grotesk Variable', system-ui, sans-serif;
+  --sl-font-mono: 'IBM Plex Mono', ui-monospace, monospace;
+  --kit-font-display: 'Schibsted Grotesk Variable', system-ui, sans-serif;
+
+  --sl-color-white: #eef3f1;
+  --sl-color-gray-1: #d5dedf;
+  --sl-color-gray-2: #aebbbf;
+  --sl-color-gray-3: #7d8d94;
+  --sl-color-gray-4: #4a5a62;
+  --sl-color-gray-5: #263137;
+  --sl-color-gray-6: #151c20;
+  --sl-color-black: #0d1215;
+  --sl-color-accent-low: #12301f;
+  --sl-color-accent: #5fd39a;
+  --sl-color-accent-high: #c4f2d6;
+  --sl-color-orange-low: #3a2a12;
+  --sl-color-orange: #c98a3a;
+  --sl-color-orange-high: #e0a85a;
+}
+
+:root[data-theme='light'] {
+  --sl-color-white: #10181a;
+  --sl-color-gray-1: #222b2c;
+  --sl-color-gray-2: #3a4645;
+  --sl-color-gray-3: #5d6b69;
+  --sl-color-gray-4: #8a9894;
+  --sl-color-gray-5: #b9c4c0;
+  --sl-color-gray-6: #e4e9e5;
+  --sl-color-gray-7: #eef1ee;
+  --sl-color-black: #f4f6f3;
+  --sl-color-accent-low: #cfeedd;
+  --sl-color-accent: #17714a;
+  --sl-color-accent-high: #0b4029;
+  --sl-color-orange-low: #f5e2c4;
+  --sl-color-orange: #b07a2a;
+  --sl-color-orange-high: #6e4a0e;
+}
+
+:is(h1, h2, h3, .site-title, .card .title) {
+  font-family: var(--kit-font-display);
+  font-weight: 800;
+  letter-spacing: -0.03em;
+}

package/packages/docs-kit/themes/vortex.css

@@ -0,0 +1,45 @@
+/* Plum-tinted neutrals with a coral accent; Outfit SemiBold headings over the system sans. */
+@import '@fontsource/outfit/600.css';
+
+:root {
+  --kit-font-display: 'Outfit', system-ui, sans-serif;
+
+  --sl-color-white: #f7f4fc;
+  --sl-color-gray-1: #e9e4f2;
+  --sl-color-gray-2: #c9c1d8;
+  --sl-color-gray-3: #a197b5;
+  --sl-color-gray-4: #6a5f80;
+  --sl-color-gray-5: #382c4d;
+  --sl-color-gray-6: #1c1030;
+  --sl-color-black: #120a1f;
+  --sl-color-accent-low: #4a1a22;
+  --sl-color-accent: #ff5a4e;
+  --sl-color-accent-high: #ffc9c4;
+}
+
+:root[data-theme='light'] {
+  --sl-color-white: #1c1030;
+  --sl-color-gray-1: #2a1f3d;
+  --sl-color-gray-2: #3d3250;
+  --sl-color-gray-3: #5c5270;
+  --sl-color-gray-4: #8c839c;
+  --sl-color-gray-5: #cbc4d6;
+  --sl-color-gray-6: #ece8f2;
+  --sl-color-gray-7: #f6f4f9;
+  --sl-color-black: #ffffff;
+  --sl-color-accent-low: #ffe1dd;
+  --sl-color-accent: #c22f25; /* 4.5:1 or more as text on every light background, white and tints alike */
+  --sl-color-accent-high: #7a1a14;
+}
+
+:is(h1, h2, h3, .site-title, .card .title) {
+  font-family: var(--kit-font-display);
+  font-weight: 600;
+  letter-spacing: -0.02em;
+}
+
+/* The wordmark: white on dark, plum on light, as in the logo lockups. */
+.site-title {
+  color: var(--sl-color-white);
+  letter-spacing: -0.035em;
+}

package/packages/docs-kit/versions.mjs

@@ -0,0 +1,103 @@
+#!/usr/bin/env node
+// Builds the docs of past releases next to the default branch's site in dist/: the newest patch tag (vX.Y.Z) of each
+// minor version that `versions:` in site.yaml selects, at dist/vX.Y/, and the list of all of them in dist/versions.json.
+// Each release's pages, assets and public files come from its tag; site.yaml, dependencies and the kit come from the
+// working tree, so every version is built with the current kit and theme.
+// Usage, from the docs directory after `astro build`: docs-kit-versions [--default-branch main]
+import { execFileSync, spawnSync } from 'node:child_process';
+import { cpSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseArgs } from 'node:util';
+import { parse } from 'yaml';
+
+/**
+ * Release tags grouped by minor version, newest first, each with its newest patch and its release line: the major
+ * version, or `0.<minor>` below 1.0, where semver lets every minor break. Pre-releases are skipped.
+ */
+export function minorVersions(tags) {
+  const newest = new Map();
+  for (const tag of tags) {
+    const match = /^v(\d+)\.(\d+)\.(\d+)$/.exec(tag);
+    if (!match) continue;
+    const [major, minor, patch] = match.slice(1).map(Number);
+    const name = `v${major}.${minor}`;
+    if (!newest.has(name) || newest.get(name).patch < patch) newest.set(name, { name, tag, major, minor, patch });
+  }
+  return [...newest.values()]
+    .sort((a, b) => b.major - a.major || b.minor - a.minor)
+    .map(({ name, tag, major, minor }) => ({ name, tag, line: major ? `${major}` : `0.${minor}` }));
+}
+
+/**
+ * The minor versions to publish, newest first: the `minors` newest, the newest of each of the `majors` newest release
+ * lines, and the pinned ones.
+ */
+export function selectVersions(candidates, { majors = 3, minors = 3, pin = [] } = {}) {
+  const lines = [...new Set(candidates.map((c) => c.line))].slice(0, majors);
+  const newestOfLine = lines.map((line) => candidates.find((c) => c.line === line));
+  return candidates.filter((c, i) => i < minors || newestOfLine.includes(c) || pin.includes(c.name));
+}
+
+// Copied from a tag into the build: content replaces the working tree's, the others are laid over it so that files
+// site.yaml names (logo, art) stay present.
+const fromTag = ['src/content/docs', 'src/assets', 'public'];
+const skipped = /^(node_modules|dist|\.astro)(\/|$)/;
+
+function main() {
+  const { values } = parseArgs({ options: { 'default-branch': { type: 'string', default: 'main' } } });
+  const site = parse(readFileSync('site.yaml', 'utf8'));
+  if (!site.versions) throw new Error('site.yaml has no `versions:`; nothing to build');
+
+  const git = (...args) => execFileSync('git', args, { encoding: 'utf8' });
+  // `<tag>:./<path>` resolves the path against the working directory, wherever the docs directory is in the repo.
+  const has = (tag, path) => spawnSync('git', ['cat-file', '-e', `${tag}:./${path}`]).status === 0;
+  const candidates = minorVersions(git('tag', '--list', 'v*').split('\n')).filter(({ tag }) => has(tag, fromTag[0]));
+  for (const name of (site.versions.pin ?? []).filter((n) => !candidates.some((c) => c.name === n))) {
+    console.log(`::warning::Pinned docs version ${name} has no vX.Y.Z tag with ${fromTag[0]}`);
+  }
+
+  const built = [];
+  for (const { name, tag } of selectVersions(candidates, site.versions)) {
+    const out = resolve('dist', name);
+    // Inside the docs directory, so the build finds node_modules by walking up; a symlink confuses Astro's paths.
+    mkdirSync('.astro', { recursive: true });
+    const work = mkdtempSync(resolve('.astro/version-'));
+    try {
+      cpSync('.', work, { recursive: true, filter: (src) => !skipped.test(relative('.', src)) });
+      rmSync(join(work, fromTag[0]), { recursive: true });
+      // Pathspecs are relative to the working directory, and so are the archived paths.
+      const archive = execFileSync('git', ['archive', tag, '--', ...fromTag.filter((p) => has(tag, p))], {
+        maxBuffer: 1 << 30,
+      });
+      execFileSync('tar', ['-x', '-C', work], { input: archive });
+      console.log(`Building ${name} from ${tag}`);
+      const astro = resolve('node_modules/.bin/astro');
+      const result = spawnSync(astro, ['build', '--outDir', out], {
+        cwd: work,
+        env: { ...process.env, DOCS_KIT_VERSION: name },
+        stdio: 'inherit',
+      });
+      if (result.status !== 0) throw new Error(`astro build exited with ${result.status ?? result.signal}`);
+      built.push(name);
+    } catch (error) {
+      // One release that no longer builds with the current kit must not block publishing the others.
+      console.log(`::warning::Skipped the ${name} docs (${tag}): ${error.message}`);
+      rmSync(out, { recursive: true, force: true });
+    } finally {
+      rmSync(work, { recursive: true, force: true });
+    }
+  }
+
+  const latest = candidates[0]?.name;
+  const versions = [
+    { name: values['default-branch'], path: '' },
+    ...built.map((name) => ({ name, path: `${name}/`, ...(name === latest && { latest: true }) })),
+  ];
+  mkdirSync('dist', { recursive: true });
+  writeFileSync('dist/versions.json', `${JSON.stringify(versions, null, 2)}\n`);
+  console.log(`Wrote dist/versions.json: ${versions.map((v) => v.name).join(', ')}`);
+}
+
+// npx runs this through a symlink in node_modules/.bin; tests import it for minorVersions.
+if (process.argv[1] && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) main();

package/refgen/help2md.mjs

@@ -0,0 +1,85 @@
+#!/usr/bin/env node
+// Walks `<bin> [sub...] --help` recursively and writes one Starlight Markdown page per command.
+// Usage: node refgen/help2md.mjs --bin <path-or-name> [--out <dir>]
+import { execFileSync } from 'node:child_process';
+import { mkdirSync, readdirSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { parseArgs } from 'node:util';
+
+// Fixed width and no colors so output is identical on every machine and CI run. Only PATH is inherited:
+// clap's `env` feature prints each variable's current value in --help (`[env: KASHA_TOKEN=secret]`),
+// which would put local secrets into committed pages and make them differ from CI's.
+const ENV = { PATH: process.env.PATH, COLUMNS: '100', NO_COLOR: '1', CLICOLOR: '0', TERM: 'dumb' };
+const MAX_DEPTH = 8;
+
+const help = (bin, path) =>
+  execFileSync(bin, [...path, '--help'], { env: ENV, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
+    .split('\n').map((l) => l.trimEnd()).join('\n').trim();
+
+// Subcommand names from clap ("Commands:", clap 3 "SUBCOMMANDS:") and cobra ("Available Commands:",
+// "Additional Commands:", command-group titles) sections. Entries sit at a 2-space indent; deeper
+// lines are wrapped descriptions.
+function subcommands(text) {
+  const names = [];
+  let inSection = false;
+  for (const line of text.split('\n')) {
+    if (/^(\w[\w ]*)?commands:$/i.test(line)) inSection = true;
+    else if (!line.trim() || /^\S/.test(line)) inSection = false;
+    else if (inSection) {
+      const m = /^ {2}([\w][\w.-]*)(?:\s+(.*))?$/.exec(line);
+      if (m && !skip(m[1], m[2] ?? '')) names.push(m[1]);
+    }
+  }
+  return names;
+}
+
+// `help` only repeats other pages. Cobra's default `completion` is identical boilerplate in every
+// cobra CLI, so it is recognised by its stock description; a project's own `completion` stays.
+const skip = (name, desc) =>
+  name === 'help' || (name === 'completion' && desc.startsWith('Generate the autocompletion script'));
+
+function page(title, text) {
+  const description = text.split('\n')[0];
+  const fence = '`'.repeat(Math.max(3, ...(text.match(/`+/g) ?? []).map((s) => s.length + 1)));
+  return [
+    '---',
+    `title: ${JSON.stringify(title)}`,
+    ...(description && !/^usage:/i.test(description) ? [`description: ${JSON.stringify(description)}`] : []),
+    '---',
+    '',
+    '<!-- Generated by docs-kit refgen/help2md from --help output. Do not edit. -->',
+    '',
+    `${fence}text`,
+    text,
+    fence,
+    '',
+  ].join('\n');
+}
+
+function generate(bin, out) {
+  const root = basename(bin).toLowerCase();
+  mkdirSync(out, { recursive: true });
+  // Drop pages of commands that no longer exist so the "reference up to date" check sees removals.
+  // ponytail: prefix match also hits a sibling binary's pages (`kasha` vs `kasha-server`) in the same
+  // --out; give each binary its own --out if that ever happens.
+  for (const f of readdirSync(out)) {
+    if (f === `${root}.md` || (f.startsWith(`${root}-`) && f.endsWith('.md'))) rmSync(join(out, f));
+  }
+  const walk = (path) => {
+    if (path.length > MAX_DEPTH) throw new Error(`command tree deeper than ${MAX_DEPTH}: ${path.join(' ')}`);
+    const text = help(bin, path);
+    const file = [root, ...path].join('-').toLowerCase() + '.md';
+    writeFileSync(join(out, file), page([root, ...path].join(' '), text));
+    for (const sub of subcommands(text)) walk([...path, sub]);
+  };
+  walk([]);
+}
+
+const { values } = parseArgs({
+  options: { bin: { type: 'string' }, out: { type: 'string', default: 'docs/src/content/docs/reference/cli' } },
+});
+if (!values.bin) {
+  console.error('usage: help2md.mjs --bin <path-or-name> [--out <dir>]');
+  process.exit(2);
+}
+generate(values.bin, values.out);