@writedocs/generator 0.5.0 → 0.7.0

package/bin/writedocs.js

@@ -205,23 +205,60 @@ program
     throw new CliExit(1);
   });
 
+program
+  // Same shape as `broken-links`: reads the project, exits 0 (nothing
+  // found) or 1.
+  .command('a11y')
+  .description('Check accessibility - color contrast, image alt text, headings, link text')
+  .argument('[dir]', 'content directory (contains writedocs.json)', '.')
+  .action(async (dir) => {
+    const contentDir = path.resolve(process.cwd(), dir);
+    const { preflightCheck } = await import('../src/cli/preflight.js');
+    preflightCheck(contentDir);
+    const configText = fs.readFileSync(path.join(contentDir, 'writedocs.json'), 'utf-8');
+    const checking = step('Checking accessibility');
+    const { checkAccessibility } = await import('../src/lib/a11y-check.js');
+    const { formatContentIssues } = await import('../src/lib/content-check.js');
+    const result = await checkAccessibility(contentDir, configText);
+    checking.stop();
+
+    if (result.issues.length === 0) {
+      log.success(`No accessibility issues - checked writedocs.json and ${plural(result.pages, 'page')}`);
+      return;
+    }
+    const count = plural(result.issues.length, 'accessibility issue');
+    log.error(count);
+    log.line();
+    log.line(formatContentIssues(result.issues));
+    log.line();
+    log.error(`${count} - checked writedocs.json and ${plural(result.pages, 'page')}`);
+    throw new CliExit(1);
+  });
+
 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.5.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

@@ -5,8 +5,8 @@ import matter from 'gray-matter';
 import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
 import { parseOpenApiRef, openApiOperationKey, specDirName } from '../lib/openapi-ref.js';
 import { findAllPages } from '../lib/pages.js';
+import { HTTP_METHODS, collectOpenApiGroups } from '../lib/openapi-spec.js';
 
-const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
 
 /** Canonical "METHOD /path" key used everywhere an operation needs to be
  *  identified: the manifest, a hand-written page's `openapi:` frontmatter,
@@ -168,63 +168,30 @@ function buildOperations(spec) {
   return operations;
 }
 
-function rmrf(dir) {
-  fs.rmSync(dir, { recursive: true, force: true });
-}
-
-/** Walks writedocs.json's raw `navigation` tree (any shape - a bare array, or
- *  an object choosing tabs/versions/languages/dropdowns/products, plus
- *  `global.dropdowns`) looking for group nodes shaped like
- *  `{ group, openapi: { src, path } }`, however deeply nested inside
- *  hand-authored groups or containers. Runs directly against the raw
- *  JSON (before writedocs.json's own zod validation even happens - this CLI
- *  step runs first, see generateApiPages() below), so it deliberately
- *  doesn't import anything from lib/config.ts and just duck-types each
- *  node the same way lib/config.ts's own walkSections()/
- *  expandOpenApiInContainer() do. */
-function collectOpenApiGroups(navigation) {
-  const found = [];
-
-  function fromPagesItem(item) {
-    if (!item || typeof item !== 'object') return; // plain page-slug string - not a group
-    if (item.group && item.openapi) {
-      found.push(item);
-      return;
-    }
-    if (Array.isArray(item.pages)) {
-      for (const child of item.pages) fromPagesItem(child);
-    }
-    // otherwise a { label, href } link leaf - nothing to collect
-  }
-
-  function fromContainer(node) {
-    if (!node || typeof node !== 'object') return;
-    if (Array.isArray(node.pages)) {
-      for (const item of node.pages) fromPagesItem(item);
-    } else if (Array.isArray(node.tabs)) {
-      for (const t of node.tabs) fromContainer(t);
-    } else if (Array.isArray(node.versions)) {
-      for (const v of node.versions) fromContainer(v);
-    } else if (Array.isArray(node.languages)) {
-      for (const l of node.languages) fromContainer(l);
-    } else if (Array.isArray(node.dropdowns)) {
-      for (const d of node.dropdowns) fromContainer(d);
-    } else if (Array.isArray(node.products)) {
-      for (const p of node.products) fromContainer(p);
-    }
-    // otherwise a bare { href } container - nothing to collect
-  }
-
-  if (Array.isArray(navigation)) {
-    for (const item of navigation) fromPagesItem(item);
-  } else if (navigation && typeof navigation === 'object') {
-    if (Array.isArray(navigation.global?.dropdowns)) {
-      for (const d of navigation.global.dropdowns) fromContainer(d);
+/** 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 };
     }
-    fromContainer(navigation);
-  }
+    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);
+}
 
-  return found;
+function rmrf(dir) {
+  fs.rmSync(dir, { recursive: true, force: true });
 }
 
 /** Generates every page for one `{ group, openapi: { src, path } }`
@@ -288,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));
@@ -410,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 });
   }