@zebradil/docs-kit 0.0.0-stage → 0.10.0

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/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);