@writedocs/generator 0.6.0 → 0.7.0

package/bin/writedocs.js

@@ -238,20 +238,27 @@ program
 program
   .command('convert')
   .description("Convert another docs tool's config into writedocs.json")
-  .argument('[dir]', 'project directory (contains docs.json)', '.')
+  .argument('[dir]', 'project directory (contains docs.json or config.json)', '.')
   .option('--mintlify', "convert a Mintlify project's docs.json")
   .option('--docs.json', 'same as --mintlify')
+  .option('--writedocs', "convert a project from the previous writedocs (its config.json)")
+  .option('--config.json', 'same as --writedocs')
   .option('--force', 'overwrite an existing writedocs.json')
   .option('--dry-run', 'print the converted writedocs.json instead of writing it')
   .action(async (dir, options) => {
-    // --mintlify is the only source today; the flag is still required so
-    // the command reads the same once other tools are added.
-    if (!options.mintlify && !options.docsJson) {
-      log.error('Say what to convert from: writedocs convert --mintlify [dir]');
+    const mintlify = options.mintlify || options.docsJson;
+    const legacy = options.writedocs || options.configJson;
+    if (mintlify === legacy) {
+      log.error(
+        mintlify
+          ? 'Pick one: --mintlify or --writedocs.'
+          : 'Say what to convert from: writedocs convert --mintlify [dir], or --writedocs for the previous writedocs.'
+      );
       throw new CliExit(1);
     }
     const { runConvert } = await import('../src/cli/convert.js');
     await runConvert({
+      source: legacy ? 'writedocs' : 'mintlify',
       contentDir: path.resolve(process.cwd(), dir),
       force: Boolean(options.force),
       dryRun: Boolean(options.dryRun),

package/package.json

@@ -1,88 +1,91 @@
-{
-  "name": "@writedocs/generator",
-  "version": "0.6.0",
-  "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
-  "type": "module",
-  "bin": {
-    "writedocs": "./bin/writedocs.js"
-  },
-  "exports": {
-    "./components": "./src/components/index.ts",
-    "./config-schema": "./src/lib/config-schema.js"
-  },
-  "files": [
-    "bin",
-    "src",
-    "astro.config.mjs"
-  ],
-  "scripts": {
-    "dev": "node bin/writedocs.js dev",
-    "build": "node bin/writedocs.js build",
-    "init": "node bin/writedocs.js init",
-    "build:schema": "esbuild src/lib/config-schema.ts --format=esm --target=node22 --outfile=src/lib/config-schema.js",
-    "prepare": "npm run build:schema",
-    "test": "node --test \"scripts/*.test.js\""
-  },
-  "keywords": [
-    "docs",
-    "documentation",
-    "static-site-generator",
-    "mdx",
-    "astro"
-  ],
-  "homepage": "https://github.com/writedocs/writedocs#readme",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/writedocs/writedocs.git"
-  },
-  "bugs": {
-    "url": "https://github.com/writedocs/writedocs/issues"
-  },
-  "author": "Gabriel Raeder",
-  "license": "ISC",
-  "publishConfig": {
-    "access": "public"
-  },
-  "dependencies": {
-    "@apidevtools/swagger-parser": "^12.1.0",
-    "@astrojs/markdown-remark": "7.2.4",
-    "@astrojs/mdx": "^7.0.5",
-    "@astrojs/react": "^6.0.2",
-    "@astrojs/sitemap": "^3.7.3",
-    "@iconify-json/bi": "^1.2.7",
-    "@iconify-json/fa6-brands": "^1.2.6",
-    "@iconify-json/fa6-solid": "^1.2.4",
-    "@iconify-json/heroicons": "^1.2.3",
-    "@iconify-json/ion": "^1.2.7",
-    "@iconify-json/lucide": "^1.2.116",
-    "@iconify-json/mdi": "^1.2.3",
-    "@iconify-json/ri": "^1.2.10",
-    "@iconify-json/simple-icons": "^1.2.89",
-    "@iconify-json/tabler": "^1.2.35",
-    "@mdx-js/mdx": "^3.1.1",
-    "@shikijs/transformers": "^4.3.1",
-    "@tailwindcss/vite": "^4.3.2",
-    "astro": "7.2.9",
-    "astro-icon": "^1.1.5",
-    "commander": "^15.0.0",
-    "dotenv": "^17.4.2",
-    "gray-matter": "^4.0.3",
-    "jsonc-parser": "3.3.1",
-    "katex": "^0.16.47",
-    "mermaid": "^11.16.0",
-    "pagefind": "^1.5.2",
-    "react": "^19.2.8",
-    "react-dom": "^19.2.8",
-    "rehype-katex": "^7.0.1",
-    "remark-math": "^6.0.0",
-    "shiki": "^4.3.1",
-    "tailwindcss": "^4.3.2",
-    "zod": "^4.4.3"
-  },
-  "engines": {
-    "node": ">=22.12.0"
-  },
-  "devDependencies": {
-    "esbuild": "0.28.2"
-  }
+{
+  "name": "@writedocs/generator",
+  "version": "0.7.0",
+  "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
+  "type": "module",
+  "bin": {
+    "writedocs": "./bin/writedocs.js"
+  },
+  "exports": {
+    "./components": "./src/components/index.ts",
+    "./config-schema": "./src/lib/config-schema.js",
+    "./writedocs.schema.json": "./writedocs.schema.json"
+  },
+  "files": [
+    "bin",
+    "src",
+    "astro.config.mjs",
+    "writedocs.schema.json"
+  ],
+  "scripts": {
+    "dev": "node bin/writedocs.js dev",
+    "build": "node bin/writedocs.js build",
+    "init": "node bin/writedocs.js init",
+    "build:schema": "esbuild src/lib/config-schema.ts --format=esm --target=node22 --outfile=src/lib/config-schema.js",
+    "prepare": "npm run build:schema && npm run build:json-schema",
+    "test": "node --test \"scripts/*.test.js\"",
+    "build:json-schema": "node scripts/build-json-schema.mjs"
+  },
+  "keywords": [
+    "docs",
+    "documentation",
+    "static-site-generator",
+    "mdx",
+    "astro"
+  ],
+  "homepage": "https://github.com/writedocs/writedocs#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/writedocs/writedocs.git"
+  },
+  "bugs": {
+    "url": "https://github.com/writedocs/writedocs/issues"
+  },
+  "author": "Gabriel Raeder",
+  "license": "ISC",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@apidevtools/swagger-parser": "^12.1.0",
+    "@astrojs/markdown-remark": "7.2.4",
+    "@astrojs/mdx": "^7.0.5",
+    "@astrojs/react": "^6.0.2",
+    "@astrojs/sitemap": "^3.7.3",
+    "@iconify-json/bi": "^1.2.7",
+    "@iconify-json/fa6-brands": "^1.2.6",
+    "@iconify-json/fa6-solid": "^1.2.4",
+    "@iconify-json/heroicons": "^1.2.3",
+    "@iconify-json/ion": "^1.2.7",
+    "@iconify-json/lucide": "^1.2.116",
+    "@iconify-json/mdi": "^1.2.3",
+    "@iconify-json/ri": "^1.2.10",
+    "@iconify-json/simple-icons": "^1.2.89",
+    "@iconify-json/tabler": "^1.2.35",
+    "@mdx-js/mdx": "^3.1.1",
+    "@shikijs/transformers": "^4.3.1",
+    "@tailwindcss/vite": "^4.3.2",
+    "astro": "7.2.9",
+    "astro-icon": "^1.1.5",
+    "commander": "^15.0.0",
+    "dotenv": "^17.4.2",
+    "gray-matter": "^4.0.3",
+    "jsonc-parser": "3.3.1",
+    "katex": "^0.16.47",
+    "mermaid": "^11.16.0",
+    "pagefind": "^1.5.2",
+    "react": "^19.2.8",
+    "react-dom": "^19.2.8",
+    "rehype-katex": "^7.0.1",
+    "remark-math": "^6.0.0",
+    "shiki": "^4.3.1",
+    "tailwindcss": "^4.3.2",
+    "zod": "^4.4.3"
+  },
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "devDependencies": {
+    "esbuild": "0.28.2"
+  }
 }

package/src/cli/convert.js

@@ -1,24 +1,48 @@
-// `writedocs convert --mintlify [dir]` - turns a Mintlify project's
-// docs.json into writedocs.json, in the same folder, then checks the pages
-// the same way `writedocs validate` does. The conversion itself is
-// lib/mintlify-convert.js; this file is the CLI around it.
+// `writedocs convert --mintlify [dir]` / `--writedocs [dir]` - turns a
+// Mintlify project's docs.json, or a config.json from the previous writedocs,
+// into writedocs.json, in the same folder, then checks the pages the same way
+// `writedocs validate` does. The conversions themselves are
+// lib/mintlify-convert.js and lib/writedocs-legacy-convert.js; this file is
+// the CLI around them.
 import fs from 'node:fs';
 import path from 'node:path';
 import { loadMintlifyConfig, convertMintlifyConfig, formatNotes } from '../lib/mintlify-convert.js';
+import { loadLegacyConfig, convertLegacyConfig } from '../lib/writedocs-legacy-convert.js';
 import { validateDocsConfig, formatValidationIssuesDetailed } from '../lib/config-schema.js';
 import { checkContent, formatContentIssues } from '../lib/content-check.js';
 import { log, step, plural, color, displayPath, CliExit } from './output.js';
 
-export async function runConvert({ contentDir, force = false, dryRun = false }) {
-  const docsJsonPath = path.join(contentDir, 'docs.json');
-  if (!fs.existsSync(docsJsonPath)) {
-    const legacy = path.join(contentDir, 'mint.json');
-    if (fs.existsSync(legacy)) {
-      log.error("Found mint.json, Mintlify's older config format.");
-      log.detail(color.dim(`Run "npx mint upgrade" in ${contentDir} to turn it into docs.json, then run this again.`));
-    } else {
-      log.error(`No docs.json found in ${contentDir}`);
-    }
+const SOURCES = {
+  mintlify: {
+    file: 'docs.json',
+    load: loadMintlifyConfig,
+    convert: async (input) => convertMintlifyConfig(input),
+    missing(contentDir) {
+      if (fs.existsSync(path.join(contentDir, 'mint.json'))) {
+        log.error("Found mint.json, Mintlify's older config format.");
+        log.detail(color.dim(`Run "npx mint upgrade" in ${contentDir} to turn it into docs.json, then run this again.`));
+      } else {
+        log.error(`No docs.json found in ${contentDir}`);
+      }
+    },
+    domainHint: '(Mintlify sets this in its dashboard, not docs.json.)',
+  },
+  writedocs: {
+    file: 'config.json',
+    load: loadLegacyConfig,
+    convert: (input, contentDir) => convertLegacyConfig(input, contentDir),
+    missing(contentDir) {
+      log.error(`No config.json found in ${contentDir}`);
+    },
+    domainHint: '(config.json had no field for it.)',
+  },
+};
+
+export async function runConvert({ source = 'mintlify', contentDir, force = false, dryRun = false }) {
+  const from = SOURCES[source];
+  const inputPath = path.join(contentDir, from.file);
+  if (!fs.existsSync(inputPath)) {
+    from.missing(contentDir);
     throw new CliExit(1);
   }
   const outPath = path.join(contentDir, 'writedocs.json');
@@ -28,15 +52,15 @@ export async function runConvert({ contentDir, force = false, dryRun = false })
     throw new CliExit(1);
   }
 
-  let docs;
+  let input;
   try {
-    docs = loadMintlifyConfig(docsJsonPath);
+    input = from.load(inputPath);
   } catch (err) {
-    log.error(`Couldn't read ${displayPath(docsJsonPath)}: ${err.message}`);
+    log.error(`Couldn't read ${displayPath(inputPath)}: ${err.message}`);
     throw new CliExit(1);
   }
 
-  const { config, notes } = convertMintlifyConfig(docs);
+  const { config, notes } = await from.convert(input, contentDir);
   const text = `${JSON.stringify(config, null, 2)}\n`;
 
   // The result must pass writedocs' own schema - if it doesn't, that's a
@@ -54,7 +78,7 @@ export async function runConvert({ contentDir, force = false, dryRun = false })
     log.line(text);
   } else {
     fs.writeFileSync(outPath, text);
-    log.success(`Converted ${path.basename(docsJsonPath)} to ${color.bold(displayPath(outPath))}`);
+    log.success(`Converted ${from.file} to ${color.bold(displayPath(outPath))}`);
   }
 
   if (notes.length) {
@@ -87,7 +111,7 @@ export async function runConvert({ contentDir, force = false, dryRun = false })
   else log.success(summary);
   if (!config.domain) {
     log.info(
-      'Next: set "domain" in writedocs.json to your site\'s URL - it turns on sitemap.xml and absolute links for social previews. (Mintlify sets this in its dashboard, not docs.json.)'
+      `Next: set "domain" in writedocs.json to your site's URL - it turns on sitemap.xml and absolute links for social previews. ${from.domainHint}`
     );
   }
 }

package/src/cli/generate-api-pages.js

@@ -168,6 +168,28 @@ function buildOperations(spec) {
   return operations;
 }
 
+/** An operation as JSON. A recursive schema - a tree whose nodes contain
+ *  nodes - dereferences into a cycle (SwaggerParser.dereference() resolves
+ *  the $ref to the very same object), which JSON can't hold and the API
+ *  pages couldn't render anyway. Where a schema would contain itself, a
+ *  short stand-in takes its place: its type and title, marked
+ *  x-circular. Shared, non-recursive schemas are written in full each time,
+ *  as before. */
+function operationJson(operation) {
+  const ancestors = [];
+  const cut = (node) => {
+    if (node === null || typeof node !== 'object') return node;
+    if (ancestors.includes(node)) {
+      return { ...(node.type ? { type: node.type } : {}), ...(node.title ? { title: node.title } : {}), 'x-circular': true };
+    }
+    ancestors.push(node);
+    const out = Array.isArray(node) ? node.map(cut) : Object.fromEntries(Object.entries(node).map(([k, v]) => [k, cut(v)]));
+    ancestors.pop();
+    return out;
+  };
+  return JSON.stringify(cut(operation), null, 2);
+}
+
 function rmrf(dir) {
   fs.rmSync(dir, { recursive: true, force: true });
 }
@@ -233,7 +255,7 @@ async function generateApiPagesForGroup({ contentDir, generatedDocsDir, group, o
     manifest.push({ slug, method: operation.method, path: operation.path, tags: operation.tags, title, generated });
 
     const opFile = path.join(openapiOutDir, 'operations', operationFileName(operation.method, operation.path));
-    fs.writeFileSync(opFile, JSON.stringify(operation, null, 2));
+    fs.writeFileSync(opFile, operationJson(operation));
   }
 
   fs.writeFileSync(path.join(openapiOutDir, 'manifest.json'), JSON.stringify(manifest, null, 2));
@@ -355,7 +377,7 @@ async function parsePageSpecs({ contentDir, openapiOutDir, groupSpecs, summary }
     const outDir = path.join(openapiOutDir, '_pages', specDirName(spec), 'operations');
     fs.mkdirSync(outDir, { recursive: true });
     for (const operation of operations) {
-      fs.writeFileSync(path.join(outDir, operationFileName(operation.method, operation.path)), JSON.stringify(operation, null, 2));
+      fs.writeFileSync(path.join(outDir, operationFileName(operation.method, operation.path)), operationJson(operation));
     }
     summary.pageSpecs.push({ spec, operations: operations.length });
   }

package/src/lib/content-check.js

@@ -10,6 +10,8 @@
 //   - writedocs.json's navigation lists a page that doesn't exist
 //   - a redirect is a pattern (`/old/:slug`) rather than one exact path
 //   - a Markdown image with a relative path names a file that doesn't exist
+//   - an import the build can't resolve: a Docusaurus path (@site/...), or a
+//     relative or /snippets/ import of a file that isn't there
 //   - an OpenAPI group's spec is missing or doesn't parse, or two groups
 //     share one `openapi.path`
 // Warnings - the build succeeds, but not as written:
@@ -129,6 +131,45 @@ async function checkPage(contentDir, rel, errors, warnings, openapiRefs) {
     );
     return;
   }
+  // Imports the build can't resolve fail it: Docusaurus' path aliases
+  // (common in pages from the previous writedocs), and a relative or
+  // /snippets/ import of a file that isn't there. Package imports aren't
+  // checked - whether they resolve depends on what's installed.
+  visit(tree, 'mdxjsEsm', (node) => {
+    const code = String(node.value ?? '');
+    for (const m of code.matchAll(/\b(?:import|export)\b[^'";]*?\bfrom\s*['"]([^'"]+)['"]|\bimport\s*['"]([^'"]+)['"]/g)) {
+      const spec = m[1] ?? m[2];
+      const at = node.position?.start?.line ? node.position.start.line + lineOffset + code.slice(0, m.index).split('\n').length - 1 : undefined;
+      if (/^@(site|theme|docusaurus|generated)(\/|$)/.test(spec)) {
+        errors.push(
+          issue(
+            rel,
+            at,
+            `Imports "${spec}", a Docusaurus path - the build fails on it.`,
+            /^@site\/src\/components\/?$/.test(spec)
+              ? "writedocs' components (Card, Callout, Tabs, Accordion, ...) need no import - remove this line."
+              : spec.startsWith('@site/src/components/')
+                ? 'A custom component of the old site - move it into a snippet (snippets/), or remove it and what uses it.'
+                : 'Remove the import, and what uses it.'
+          )
+        );
+        continue;
+      }
+      let target = null;
+      if (spec.startsWith('./') || spec.startsWith('../')) target = path.resolve(path.dirname(path.join(contentDir, rel)), spec);
+      else if (spec.startsWith('/snippets/')) target = path.join(contentDir, spec);
+      if (!target) continue;
+      const exists = ['', '.mdx', '.md', '.js', '.jsx', '.ts', '.tsx', '.json'].some((ext) => {
+        try {
+          return fs.statSync(target + ext).isFile();
+        } catch {
+          return false;
+        }
+      });
+      if (!exists) errors.push(issue(rel, at, `Imports ${spec}, which doesn't exist - the build fails on it.`));
+    }
+  });
+
   // A Markdown image with a relative path is imported by the build (Astro's
   // image pipeline), so a missing file fails the whole build.
   visit(tree, 'image', (node) => {

package/src/lib/json-schema-descriptions.js

@@ -0,0 +1,204 @@
+// The editor help text for writedocs.schema.json (see lib/json-schema.js):
+// one entry per field of writedocs.json, keyed by its path - `a.b.c`, with
+// `[]` for an array's items. Fields inside the navigation's recursive types
+// are keyed by the type's name instead (`Tab.icon`, `NavigationItem.group`).
+//
+// scripts/json-schema.test.js fails when a field has no entry here, or an
+// entry names a field that doesn't exist - so a new field in
+// config-schema.ts needs its description added here too.
+
+const CHILDREN = {
+  pages: 'The pages and groups in this section of the sidebar.',
+  tabs: 'Tabs inside this one.',
+  versions: 'Versions inside this one - a version picker in the sidebar.',
+  languages: 'Languages inside this one - a language picker.',
+  dropdowns: 'Dropdowns inside this one - a menu of sections in the sidebar.',
+  products: 'Products inside this one - a product picker.',
+  href: 'Makes this a link to another address instead of a section with pages of its own.',
+};
+
+const CONTAINERS = {
+  Tab: {
+    tab: 'The tab\'s name, shown in the topbar.',
+    icon: 'Icon next to the name: a Lucide name ("book-open"), "collection:name" ("mdi:server"), an emoji, or an image path.',
+  },
+  Version: {
+    version: 'The version\'s name, like "v2".',
+    label: 'Text shown in the version picker instead of `version`.',
+    tag: 'A short badge next to the version, like "Latest" or "Deprecated".',
+    default: 'Open this version first. Without it, the first version is the default.',
+  },
+  Language: {
+    language: 'The language code, like "en" or "pt-BR".',
+    label: 'Text shown in the language picker instead of `language`, like "Português".',
+  },
+  Dropdown: {
+    dropdown: 'The dropdown\'s name.',
+    icon: 'Icon next to the name: a Lucide name, "collection:name", an emoji, or an image path.',
+  },
+  Product: {
+    product: 'The product\'s name, shown in the product picker.',
+    icon: 'Icon next to the name: a Lucide name, "collection:name", an emoji, or an image path.',
+    description: 'One line under the name in the product picker.',
+  },
+};
+
+const containerEntries = Object.entries(CONTAINERS).flatMap(([type, fields]) => [
+  ...Object.entries(fields).map(([field, text]) => [`${type}.${field}`, text]),
+  ...Object.entries(CHILDREN).map(([field, text]) => [`${type}.${field}`, text]),
+]);
+
+const logo = (where) => ({
+  [where]: 'The logo: one image path for both color modes, or `{ light, dark, label }` with an image per mode.',
+  [`${where}.light`]: 'Logo image shown in light mode.',
+  [`${where}.dark`]: 'Logo image shown in dark mode.',
+  [`${where}.label`]: 'Text shown next to the logo. No text is shown by default - a logo is usually already a wordmark.',
+});
+
+const font = (where, what) => ({
+  [`${where}.family`]: `Font family for ${what}. A Google Fonts name loads automatically; add \`source\` for a font file instead.`,
+  [`${where}.weight`]: `Font weight for ${what}, like 400 or 700.`,
+  [`${where}.source`]: 'Path or URL of a font file to load, instead of Google Fonts.',
+  [`${where}.format`]: 'Format of the `source` font file.',
+});
+
+const link = (where) => ({
+  [`${where}.label`]: 'Link text. A link needs a label, an icon, or both.',
+  [`${where}.href`]: 'Where the link goes - a site path like "/docs/intro/" or a full URL.',
+  [`${where}.icon`]: 'Icon shown with the link: a Lucide name, "collection:name", an emoji, or an image path.',
+});
+
+const script = (where) => ({
+  [`${where}.src`]: 'URL of the script to load. Use either `src` or `content`, not both.',
+  [`${where}.content`]: 'The script\'s code, inline. Use either `src` or `content`, not both.',
+});
+
+export const ROOT_DESCRIPTION = 'Configuration of a writedocs site: its name, look, navigation and integrations.';
+
+export const TYPE_DESCRIPTIONS = {
+  NavigationItem: 'A page (its path from the project folder, without the extension), a group of pages, or a link.',
+  Tab: 'A tab in the topbar, with its own sidebar.',
+  Version: 'A version of the docs, chosen from a version picker.',
+  Language: 'A language of the docs, chosen from a language picker.',
+  Dropdown: 'A section chosen from a dropdown menu.',
+  Product: 'A product, chosen from a product picker.',
+};
+
+export const DESCRIPTIONS = {
+  $schema: 'The JSON Schema this file follows - for editor autocompletion and checks.',
+  name: 'Required. The site\'s name - shown in the browser tab ("Page title · name") and as the topbar text when there\'s no logo.',
+  description: 'Description used for pages that don\'t set their own `description` in frontmatter.',
+
+  styles: 'Colors, logo, favicon, fonts, code block themes, navbar and background.',
+  'styles.colors': 'The site\'s colors.',
+  'styles.colors.primary': 'Main color: links, buttons, the active page in the sidebar. Default "#6366f1".',
+  'styles.colors.text': 'Body text color in light mode. Default "#0f172a".',
+  'styles.colors.dark': 'Dark-mode colors. Anything left out uses the light-mode value.',
+  'styles.colors.dark.primary': 'Main color in dark mode. Pick a lighter one if `primary` is dark - links use it on a dark background.',
+  'styles.colors.dark.text': 'Body text color in dark mode. Default "#e2e8f0".',
+  ...logo('styles.logo'),
+  'styles.favicon': 'Favicon image path.',
+  'styles.fonts': 'Fonts. Default: Inter. `heading` and `body` override just that part; anything they leave out comes from the top-level fields.',
+  ...font('styles.fonts', 'all text'),
+  'styles.fonts.heading': 'Font for headings only.',
+  ...font('styles.fonts.heading', 'headings'),
+  'styles.fonts.body': 'Font for body text only.',
+  ...font('styles.fonts.body', 'body text'),
+  'styles.codeblocks': 'Syntax-highlighting themes for code blocks and the API playground.',
+  'styles.codeblocks.light': 'Shiki theme name for light mode (https://shiki.style/themes). Default "github-light".',
+  'styles.codeblocks.dark': 'Shiki theme name for dark mode. Default "github-dark".',
+  'styles.codeblocks.langAlias': 'Extra language names for code blocks, mapped to a language Shiki knows - like { "curl": "bash" }.',
+  'styles.navbar': 'The topbar\'s own background. Without it, the topbar matches the page background. Its text turns black or white automatically.',
+  'styles.navbar.light': 'Topbar in light mode: a background color, or `{ background, accent }`.',
+  'styles.navbar.light.background': 'Topbar background color in light mode.',
+  'styles.navbar.light.accent': 'Color of the active tab and hover states in the topbar, in place of `styles.colors.primary`.',
+  'styles.navbar.dark': 'Topbar in dark mode: a background color, or `{ background, accent }`.',
+  'styles.navbar.dark.background': 'Topbar background color in dark mode.',
+  'styles.navbar.dark.accent': 'Color of the active tab and hover states in the topbar, in dark mode.',
+  'styles.background': 'Background color of the site, and an optional background image.',
+  'styles.background.colors': 'Background colors.',
+  'styles.background.colors.light': 'Background color in light mode. Default "#ffffff".',
+  'styles.background.colors.dark': 'Background color in dark mode. Default "#0b1120".',
+  'styles.background.images': 'Background images, shown behind the content and sidebar.',
+  'styles.background.images.light': 'Background image in light mode.',
+  'styles.background.images.dark': 'Background image in dark mode.',
+
+  navigation:
+    'Required. The site\'s structure: a list of pages and groups, or an object with exactly one of `tabs`, `versions`, `languages`, `dropdowns` or `products`. Those can nest inside each other.',
+  'navigation.global': 'Dropdowns shown on every page, whatever section is open.',
+  'navigation.global.dropdowns': 'Dropdowns shown on every page.',
+  'navigation.tabs': 'Tabs in the topbar, each with its own sidebar.',
+  'navigation.versions': 'Versions of the docs, with a version picker.',
+  'navigation.languages': 'Languages of the docs, with a language picker.',
+  'navigation.dropdowns': 'Sections chosen from a dropdown menu.',
+  'navigation.products': 'Products, with a product picker.',
+
+  'NavigationItem.group': 'The group\'s name in the sidebar.',
+  'NavigationItem.page': 'A page the group\'s name links to.',
+  'NavigationItem.pages': 'The pages and groups inside this group.',
+  'NavigationItem.openapi': 'Generate this group\'s pages from an OpenAPI spec - a page per operation, grouped by tag.',
+  'NavigationItem.openapi.src': 'Path of the OpenAPI spec file, relative to writedocs.json.',
+  'NavigationItem.openapi.path': 'URL path the generated pages go under, like "/api". Each OpenAPI group needs its own.',
+  'NavigationItem.label': 'Link text in the sidebar.',
+  'NavigationItem.href': 'Where the link goes.',
+  ...Object.fromEntries(containerEntries),
+
+  socials: 'Icon links in the footer: platform -> URL, like { "github": "https://github.com/acme" }. The key is also the icon.',
+  topbar: 'The topbar.',
+  'topbar.links': 'Links at the right of the topbar.',
+  ...link('topbar.links[]'),
+  footer: 'The footer: columns of links, and the `socials` icons.',
+  'footer.columns': 'Columns of links.',
+  'footer.columns[].title': 'The column\'s heading. Optional.',
+  'footer.columns[].links': 'The links in the column.',
+  ...link('footer.columns[].links[]'),
+  ...logo('footer.logo'),
+
+  api: 'The API playground.',
+  'api.proxy': 'Send "Try it" requests through writedocs\' proxy, for APIs that don\'t allow calls from other sites (CORS). Default true.',
+  domain: 'The site\'s address, like "docs.example.com". Turns on sitemap.xml and absolute URLs in link previews.',
+
+  seo: 'Default metadata for every page. A page\'s own `seo` frontmatter overrides it field by field.',
+  'seo.ogImage': 'Image shown in link previews - a path or a full URL.',
+  'seo.ogType': 'The og:type of pages. Default "website".',
+  'seo.twitterCard': 'X/Twitter card style. Default "summary_large_image" with an `ogImage`, "summary" without.',
+  'seo.keywords': 'Keywords for the <meta name="keywords"> tag.',
+  'seo.noindex': 'Ask search engines not to index pages, and leave them out of sitemap.xml.',
+  contextMenu: 'Adds a "Copy page" menu to pages - copy as Markdown, or open the page in an AI assistant - and a Markdown copy of each page at its address + ".md".',
+  'contextMenu.openIn': 'Which AI assistants the menu offers. Default: all three.',
+  redirects: 'Redirects from old addresses. Each matches one exact path.',
+  'redirects[].source': 'The old path, like "/old-page".',
+  'redirects[].destination': 'Where to send it, like "/docs/new-page/".',
+  variables: 'Values pages can insert with [[name]], like { "productName": "Acme" }.',
+  banner: 'A banner above the topbar on every page.',
+  'banner.content': 'The banner\'s text. Markdown links work.',
+  'banner.dismissible': 'Let readers close it. Default false.',
+  'banner.type': 'Its color: "info", "warning" or "critical". Default "info".',
+  notFound: 'The 404 page.',
+  'notFound.title': 'The 404 page\'s title.',
+  'notFound.description': 'Text under the title on the 404 page.',
+  scripts: 'Scripts added to every page - for tools `integrations` doesn\'t cover.',
+  'scripts.head': 'Scripts added at the end of <head>.',
+  ...script('scripts.head[]'),
+  'scripts.body': 'Scripts added at the end of <body>.',
+  ...script('scripts.body[]'),
+
+  integrations: 'Analytics and chat tools.',
+  'integrations.ga4': 'Google Analytics 4.',
+  'integrations.ga4.measurementId': 'Measurement ID, like "G-XXXXXXXXXX".',
+  'integrations.googleTagManager': 'Google Tag Manager.',
+  'integrations.googleTagManager.containerId': 'Container ID, like "GTM-XXXXXXX".',
+  'integrations.plausible': 'Plausible Analytics.',
+  'integrations.plausible.domain': 'The site\'s domain, as registered in Plausible.',
+  'integrations.plausible.src': 'Script URL, for a self-hosted Plausible. Default "https://plausible.io/js/script.js".',
+  'integrations.fathom': 'Fathom Analytics.',
+  'integrations.fathom.siteId': 'Fathom\'s site ID, like "ABCDEFGH".',
+  'integrations.posthog': 'PostHog.',
+  'integrations.posthog.apiKey': 'Project API key, starting with "phc_".',
+  'integrations.posthog.apiHost': 'API host. Default "https://us.i.posthog.com" - use yours for EU cloud or self-hosting.',
+  'integrations.umami': 'Umami Analytics.',
+  'integrations.umami.websiteId': 'Umami\'s website ID.',
+  'integrations.umami.src': 'Script URL. Default "https://cloud.umami.is/script.js" - use yours when self-hosting.',
+  'integrations.askAi': 'AI chat over the docs, with DocsBot.',
+  'integrations.askAi.id': 'DocsBot\'s "teamId/botId". The WRITEDOCS_ASK_AI_ID environment variable overrides it.',
+};