@writedocs/generator 0.4.8 → 0.4.10

package/astro.config.mjs

@@ -26,7 +26,14 @@ import { remarkAutoHydrateSnippets } from './src/lib/mdx-auto-hydrate.js';
 import { remarkInjectBuiltinComponents } from './src/lib/mdx-inject-builtins.js';
 import { remarkTitleAnchorIds } from './src/lib/mdx-title-anchor-ids.js';
 import { remarkSubstituteVariables } from './src/lib/mdx-substitute-variables.js';
-import { remarkMintlifyTreeLists, remarkMintlifyPromptText } from './src/lib/mdx-mintlify.js';
+import {
+  remarkMintlifyTreeLists,
+  remarkMintlifyPromptText,
+  remarkMintlifyReactHooks,
+  mintlifyReactHooksPlugin,
+} from './src/lib/mdx-mintlify.js';
+import { remarkUnknownComponentFallback } from './src/lib/mdx-unknown-components.js';
+import { remarkExtractInlineReactComponents } from './src/lib/mdx-inline-react.js';
 import { writedocsTempDir, writedocsBuildStagingDir } from './src/lib/writedocs-temp-dir.js';
 import { stylesAssetFallback } from './src/lib/styles-asset-integration.js';
 import {
@@ -46,6 +53,13 @@ const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
 // does the actual cross-filesystem-safe copy into contentDir/dist as an
 // explicit final step once the build itself is done.
 const packageRoot = process.env.WRITEDOCS_PACKAGE_ROOT || path.dirname(fileURLToPath(import.meta.url));
+// Where this package's dependencies are: the node_modules folder that
+// contains an installed package (<project>/node_modules/@writedocs/
+// generator -> <project>/node_modules), or packageRoot itself in a checkout,
+// whose own node_modules is inside it. Used for the dev server's file-serving
+// allow list below.
+const nodeModulesAt = packageRoot.lastIndexOf(`${path.sep}node_modules${path.sep}`);
+const dependencyRoot = nodeModulesAt === -1 ? packageRoot : packageRoot.slice(0, nodeModulesAt + `${path.sep}node_modules`.length);
 
 // Read here (rather than deferred to page-render time, where
 // loadDocsConfig() is also called from [...slug].astro) specifically so
@@ -370,6 +384,19 @@ export default defineConfig({
         // the tree when it looks for components to import.
         remarkMintlifyTreeLists,
         remarkMintlifyPromptText,
+        // An inline component that calls React hooks moves into a generated
+        // .jsx file so it runs as real React (and hydrates) - see
+        // lib/mdx-inline-react.js. Before remarkMintlifyReactHooks, which
+        // imports any hooks the page itself still calls (Mintlify
+        // pre-injects them), and before remarkAutoHydrateSnippets, which
+        // hydrates the component through its new .jsx import.
+        remarkExtractInlineReactComponents,
+        remarkMintlifyReactHooks,
+        // An unknown component becomes a fragment (its children still
+        // render) with a warning, instead of failing the whole build - see
+        // lib/mdx-unknown-components.js. After remarkMintlifyTreeLists, so
+        // the <Tree.Folder>/<Tree.File> elements it adds count as known.
+        remarkUnknownComponentFallback,
         remarkInjectBuiltinComponents,
         // Runs after remarkInjectBuiltinComponents (order doesn't actually
         // matter between them - that plugin only ever prepends an import
@@ -435,10 +462,26 @@ export default defineConfig({
   // working. See src/styles/global.css for the one @import that wires
   // Tailwind's utilities in.
   vite: {
+    // The dev server only serves files under its workspace root by default.
+    // A site's own snippets live in its content directory, and inline React
+    // components moved out of pages (lib/mdx-inline-react.js) in writedocs'
+    // temp directory - both need to reach the browser to hydrate. Setting
+    // `allow` replaces Vite's default rather than adding to it, so the
+    // package's dependencies must stay reachable too: when writedocs is
+    // installed, they sit next to it in the node_modules folder that
+    // contains it (React's own hydration client included), not inside
+    // packageRoot - see dependencyRoot above.
+    server: {
+      fs: {
+        allow: [packageRoot, dependencyRoot, contentDir, writedocsTempDir(contentDir)],
+      },
+    },
     // contentTailwindSource() must come before tailwindcss(): both are
     // enforce: 'pre' transforms, which Vite runs in array order, and
     // Tailwind has to see the added @source when it compiles global.css.
-    plugins: [contentTailwindSource(), tailwindcss()],
+    // mintlifyReactHooksPlugin() does for a site's .jsx/.tsx snippets what
+    // remarkMintlifyReactHooks does for its MDX pages.
+    plugins: [contentTailwindSource(), tailwindcss(), mintlifyReactHooksPlugin(contentDir)],
     resolve: {
       alias: [
         // Lets a page's MDX write `import Foo from '/snippets/foo.mdx'`

package/bin/writedocs.js

@@ -1,139 +1,190 @@
-#!/usr/bin/env node
-import { Command } from 'commander';
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import dotenv from 'dotenv';
-import { runDev } from '../src/cli/dev.js';
-import { runBuild } from '../src/cli/build.js';
-import { runInit } from '../src/cli/init.js';
-import { requireBuildKey } from '../src/cli/build-auth.js';
-// O MESMO modulo que o build usa (via loadDocsConfig, que reexporta daqui) e
-// que a plataforma importa por `@writedocs/generator/config-schema` - e o que
-// faz os tres reportarem os mesmos problemas com as mesmas palavras, em vez de
-// cada um manter a sua copia do schema.
-//
-// `.js`, e nao o `.ts` que e a fonte de verdade: este arquivo e carregado por
-// node puro, sem o transform do Astro/Vite, e o Node RECUSA type stripping para
-// qualquer arquivo sob node_modules - por desenho, em qualquer versao
-// (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING). Ou seja: importar o `.ts` aqui
-// funciona a partir do checkout e falha 100% das vezes para quem instala o
-// pacote, que foi exatamente o que quebrou o `validate` no 0.2.0. O `.js` e
-// gerado do `.ts` pelo script `prepare` (package.json), entao ele existe tanto
-// no checkout quanto dentro do tarball, e o consumidor nao roda build nenhum.
-// Ver a mesma regra ja escrita em src/cli/write-redirects-file.js.
-import {
-  validateDocsConfig,
-  formatValidationIssuesDetailed,
-  unknownRootKeyIssues,
-} from '../src/lib/config-schema.js';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const packageRoot = path.resolve(__dirname, '..');
-// Read rather than hardcode - a literal version string here silently drifts
-// from package.json's own "version" the moment either one is bumped without
-// the other (exactly what `npm version <bump>` does: it only touches
-// package.json). `writedocs --version` should always reflect what actually
-// got published, not whatever this string happened to say at the time this
-// line was last hand-edited.
-const { version } = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
-
-const program = new Command();
-program
-  .name('writedocs')
-  .description('Static site generator for writedocs.json + MDX')
-  .version(version);
-
-program
-  .command('dev')
-  .description('Start a local dev server with hot reload')
-  .argument('[dir]', 'content directory (contains writedocs.json and docs/)', '.')
-  .option('-p, --port <port>', 'port to run on')
-  .action(async (dir, opts) => {
-    await runDev({
-      contentDir: path.resolve(process.cwd(), dir),
-      packageRoot,
-      port: opts.port,
-    });
-  });
-
-program
-  // { hidden: true } keeps `build` out of `writedocs --help` - it's not a
-  // command ordinary users are meant to discover or run themselves. See
-  // src/cli/build-auth.js for the second layer: even someone who knows the
-  // command exists still can't run it without the right key.
-  .command('build', { hidden: true })
-  .description('Build a static site into <dir>/dist')
-  .argument('[dir]', 'content directory (contains writedocs.json and docs/)', '.')
-  .option('-k, --key <key>', 'build authorization key (or set WRITEDOCS_API_KEY)')
-  .action(async (dir, opts) => {
-    const contentDir = path.resolve(process.cwd(), dir);
-    // Project-scoped, not global: a .env sitting next to this project's own
-    // writedocs.json (WRITEDOCS_KEY_SERVER_URL, WRITEDOCS_API_KEY) is picked
-    // up automatically, so build doesn't need those exported by hand every
-    // session. dotenv never overwrites a var already set in the real
-    // environment - an explicit `export`/CI secret still wins over the file.
-    dotenv.config({ path: path.join(contentDir, '.env'), quiet: true });
-    await requireBuildKey(opts.key || process.env.WRITEDOCS_API_KEY);
-    await runBuild({ contentDir, packageRoot });
-  });
-
-program
-  // Visivel, ao contrario do `build`: validar a propria configuracao e
-  // exatamente o tipo de coisa que um usuario deve poder rodar sozinho, no CI
-  // inclusive. Sem chave, sem dotenv, sem rede - le um arquivo e sai 0 ou 1.
-  .command('validate')
-  .description('Validate writedocs.json against the schema')
-  .argument('[dir]', 'content directory (contains writedocs.json)', '.')
-  .action(async (dir) => {
-    const contentDir = path.resolve(process.cwd(), dir);
-    const configPath = path.join(contentDir, 'writedocs.json');
-    if (!fs.existsSync(configPath)) {
-      // Mesma mensagem que loadDocsConfig() ja da pro mesmo caso.
-      console.error(
-        `[writedocs] writedocs.json not found at ${configPath}. Run "writedocs init" to scaffold one.`
-      );
-      process.exit(1);
-    }
-
-    const rawText = fs.readFileSync(configPath, 'utf-8');
-    const result = validateDocsConfig(rawText);
-    // Chave desconhecida na raiz e AVISO, nunca erro: a raiz nao e `.strict()`
-    // de proposito (tornar strict quebraria configs existentes), entao o Zod
-    // descarta a chave em silencio. Sem JSON parseavel nao ha chave pra avaliar.
-    const warnings = result.kind === 'invalid_json' ? [] : unknownRootKeyIssues(rawText);
-    const nomeArquivo = path.basename(configPath);
-
-    if (!result.ok) {
-      // A versao longa (linha, frase humana, sugestao) em vez da curta que o
-      // `writedocs build` imprime: aqui o usuario pediu explicitamente um
-      // diagnostico, e tem a tela inteira pra ele.
-      console.error(`[writedocs] ${configPath} failed validation:\n`);
-      console.error(formatValidationIssuesDetailed(result.issues, { fileName: nomeArquivo }));
-      console.error('');
-    }
-
-    if (warnings.length > 0) {
-      console.error(`[writedocs] ${warnings.length} warning${warnings.length === 1 ? '' : 's'}:\n`);
-      console.error(formatValidationIssuesDetailed(warnings, { fileName: nomeArquivo }));
-      console.error('');
-    }
-
-    if (!result.ok) process.exit(1);
-    // Aviso nao invalida: um config so com avisos continua valido, e sai 0 -
-    // o mesmo criterio que a plataforma usa pra marcar o projeto como `valid`.
-    console.log(`[writedocs] ${configPath} is valid.`);
-  });
-
-program
-  .command('init')
-  .description('Scaffold a writedocs.json and starter docs/ folder')
-  .argument('[dir]', 'directory to scaffold into', '.')
-  .action(async (dir) => {
-    await runInit({ targetDir: path.resolve(process.cwd(), dir) });
-  });
-
-program.parseAsync(process.argv).catch((err) => {
-  console.error(`[writedocs] ${err.message}`);
-  process.exit(1);
-});
+#!/usr/bin/env node
+import { Command } from 'commander';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import dotenv from 'dotenv';
+import { runDev } from '../src/cli/dev.js';
+import { runBuild } from '../src/cli/build.js';
+import { runInit } from '../src/cli/init.js';
+import { requireBuildKey } from '../src/cli/build-auth.js';
+// O MESMO modulo que o build usa (via loadDocsConfig, que reexporta daqui) e
+// que a plataforma importa por `@writedocs/generator/config-schema` - e o que
+// faz os tres reportarem os mesmos problemas com as mesmas palavras, em vez de
+// cada um manter a sua copia do schema.
+//
+// `.js`, e nao o `.ts` que e a fonte de verdade: este arquivo e carregado por
+// node puro, sem o transform do Astro/Vite, e o Node RECUSA type stripping para
+// qualquer arquivo sob node_modules - por desenho, em qualquer versao
+// (ERR_UNSUPPORTED_NODE_MODULES_TYPE_STRIPPING). Ou seja: importar o `.ts` aqui
+// funciona a partir do checkout e falha 100% das vezes para quem instala o
+// pacote, que foi exatamente o que quebrou o `validate` no 0.2.0. O `.js` e
+// gerado do `.ts` pelo script `prepare` (package.json), entao ele existe tanto
+// no checkout quanto dentro do tarball, e o consumidor nao roda build nenhum.
+// Ver a mesma regra ja escrita em src/cli/write-redirects-file.js.
+import {
+  validateDocsConfig,
+  formatValidationIssuesDetailed,
+  unknownRootKeyIssues,
+} from '../src/lib/config-schema.js';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const packageRoot = path.resolve(__dirname, '..');
+// Read rather than hardcode - a literal version string here silently drifts
+// from package.json's own "version" the moment either one is bumped without
+// the other (exactly what `npm version <bump>` does: it only touches
+// package.json). `writedocs --version` should always reflect what actually
+// got published, not whatever this string happened to say at the time this
+// line was last hand-edited.
+const { version } = JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf-8'));
+
+const program = new Command();
+program
+  .name('writedocs')
+  .description('Static site generator for writedocs.json + MDX')
+  .version(version);
+
+program
+  .command('dev')
+  .description('Start a local dev server with hot reload')
+  .argument('[dir]', 'content directory (contains writedocs.json and docs/)', '.')
+  .option('-p, --port <port>', 'port to run on')
+  .action(async (dir, opts) => {
+    await runDev({
+      contentDir: path.resolve(process.cwd(), dir),
+      packageRoot,
+      port: opts.port,
+    });
+  });
+
+program
+  // { hidden: true } keeps `build` out of `writedocs --help` - it's not a
+  // command ordinary users are meant to discover or run themselves. See
+  // src/cli/build-auth.js for the second layer: even someone who knows the
+  // command exists still can't run it without the right key.
+  .command('build', { hidden: true })
+  .description('Build a static site into <dir>/dist')
+  .argument('[dir]', 'content directory (contains writedocs.json and docs/)', '.')
+  .option('-k, --key <key>', 'build authorization key (or set WRITEDOCS_API_KEY)')
+  .action(async (dir, opts) => {
+    const contentDir = path.resolve(process.cwd(), dir);
+    // Project-scoped, not global: a .env sitting next to this project's own
+    // writedocs.json (WRITEDOCS_KEY_SERVER_URL, WRITEDOCS_API_KEY) is picked
+    // up automatically, so build doesn't need those exported by hand every
+    // session. dotenv never overwrites a var already set in the real
+    // environment - an explicit `export`/CI secret still wins over the file.
+    dotenv.config({ path: path.join(contentDir, '.env'), quiet: true });
+    await requireBuildKey(opts.key || process.env.WRITEDOCS_API_KEY);
+    await runBuild({ contentDir, packageRoot });
+  });
+
+program
+  // Visivel, ao contrario do `build`: validar a propria configuracao e
+  // exatamente o tipo de coisa que um usuario deve poder rodar sozinho, no CI
+  // inclusive. Sem chave, sem dotenv, sem rede - le um arquivo e sai 0 ou 1.
+  .command('validate')
+  .description('Validate writedocs.json and every page - frontmatter, MDX, navigation, components, icons')
+  .argument('[dir]', 'content directory (contains writedocs.json)', '.')
+  .option('--config-only', 'check writedocs.json only, not the pages')
+  .action(async (dir, options) => {
+    const contentDir = path.resolve(process.cwd(), dir);
+    const configPath = path.join(contentDir, 'writedocs.json');
+    if (!fs.existsSync(configPath)) {
+      // Mesma mensagem que loadDocsConfig() ja da pro mesmo caso.
+      console.error(
+        `[writedocs] writedocs.json not found at ${configPath}. Run "writedocs init" to scaffold one.`
+      );
+      process.exit(1);
+    }
+
+    const rawText = fs.readFileSync(configPath, 'utf-8');
+    const result = validateDocsConfig(rawText);
+    // Chave desconhecida na raiz e AVISO, nunca erro: a raiz nao e `.strict()`
+    // de proposito (tornar strict quebraria configs existentes), entao o Zod
+    // descarta a chave em silencio. Sem JSON parseavel nao ha chave pra avaliar.
+    const warnings = result.kind === 'invalid_json' ? [] : unknownRootKeyIssues(rawText);
+    const nomeArquivo = path.basename(configPath);
+
+    if (!result.ok) {
+      // A versao longa (linha, frase humana, sugestao) em vez da curta que o
+      // `writedocs build` imprime: aqui o usuario pediu explicitamente um
+      // diagnostico, e tem a tela inteira pra ele.
+      console.error(`[writedocs] ${configPath} failed validation:\n`);
+      console.error(formatValidationIssuesDetailed(result.issues, { fileName: nomeArquivo }));
+      console.error('');
+    }
+
+    if (warnings.length > 0) {
+      console.error(`[writedocs] ${warnings.length} warning${warnings.length === 1 ? '' : 's'}:\n`);
+      console.error(formatValidationIssuesDetailed(warnings, { fileName: nomeArquivo }));
+      console.error('');
+    }
+
+    // The pages: everything that would fail the build (errors) or build
+    // differently than written (warnings), in one pass - see
+    // src/lib/content-check.js. Runs even when writedocs.json itself is
+    // invalid, so one run reports both; only the navigation/icon checks
+    // need writedocs.json to at least be valid JSON.
+    let content = null;
+    if (!options.configOnly) {
+      const { checkContent, formatContentIssues } = await import('../src/lib/content-check.js');
+      content = await checkContent(contentDir, result.kind === 'invalid_json' ? null : rawText);
+      if (content.errors.length > 0) {
+        console.error(`[writedocs] ${content.errors.length} error${content.errors.length === 1 ? '' : 's'} in the pages:\n`);
+        console.error(formatContentIssues(content.errors));
+        console.error('');
+      }
+      if (content.warnings.length > 0) {
+        console.error(`[writedocs] ${content.warnings.length} warning${content.warnings.length === 1 ? '' : 's'} in the pages:\n`);
+        console.error(formatContentIssues(content.warnings));
+        console.error('');
+      }
+    }
+
+    if (!result.ok || (content && content.errors.length > 0)) process.exit(1);
+    // Aviso nao invalida: um config so com avisos continua valido, e sai 0 -
+    // o mesmo criterio que a plataforma usa pra marcar o projeto como `valid`.
+    console.log(`[writedocs] ${configPath} is valid.`);
+    if (content) {
+      console.log(
+        `[writedocs] Checked ${content.pages} page${content.pages === 1 ? '' : 's'}: no errors` +
+          (content.warnings.length ? `, ${content.warnings.length} warning${content.warnings.length === 1 ? '' : 's'} above.` : '.')
+      );
+    }
+  });
+
+program
+  .command('convert')
+  .description("Convert another docs tool's config into writedocs.json")
+  .argument('[dir]', 'project directory (contains docs.json)', '.')
+  .option('--mintlify', "convert a Mintlify project's docs.json")
+  .option('--docs.json', 'same as --mintlify')
+  .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) {
+      console.error('[writedocs] Say what to convert from: writedocs convert --mintlify [dir]');
+      process.exit(1);
+    }
+    const { runConvert } = await import('../src/cli/convert.js');
+    await runConvert({
+      contentDir: path.resolve(process.cwd(), dir),
+      force: Boolean(options.force),
+      dryRun: Boolean(options.dryRun),
+    });
+  });
+
+program
+  .command('init')
+  .description('Scaffold a writedocs.json and starter docs/ folder')
+  .argument('[dir]', 'directory to scaffold into', '.')
+  .action(async (dir) => {
+    await runInit({ targetDir: path.resolve(process.cwd(), dir) });
+  });
+
+program.parseAsync(process.argv).catch((err) => {
+  console.error(`[writedocs] ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.4.8",
+  "version": "0.4.10",
   "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
   "type": "module",
   "bin": {
@@ -59,6 +59,7 @@
     "@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",

package/src/cli/convert.js

@@ -0,0 +1,82 @@
+// `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.
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadMintlifyConfig, convertMintlifyConfig, formatNotes } from '../lib/mintlify-convert.js';
+import { validateDocsConfig, formatValidationIssuesDetailed } from '../lib/config-schema.js';
+import { checkContent, formatContentIssues } from '../lib/content-check.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)) {
+      console.error(
+        `[writedocs] Found mint.json, Mintlify's older config format. Run \`npx mint upgrade\` in ${contentDir} to turn it into docs.json, then run this again.`
+      );
+    } else {
+      console.error(`[writedocs] No docs.json found in ${contentDir}.`);
+    }
+    process.exit(1);
+  }
+  const outPath = path.join(contentDir, 'writedocs.json');
+  if (!dryRun && !force && fs.existsSync(outPath)) {
+    console.error(`[writedocs] ${outPath} already exists. Pass --force to overwrite it, or --dry-run to only see the result.`);
+    process.exit(1);
+  }
+
+  let docs;
+  try {
+    docs = loadMintlifyConfig(docsJsonPath);
+  } catch (err) {
+    console.error(`[writedocs] Couldn't read ${docsJsonPath}: ${err.message}`);
+    process.exit(1);
+  }
+
+  const { config, notes } = convertMintlifyConfig(docs);
+  const text = `${JSON.stringify(config, null, 2)}\n`;
+
+  // The result must pass writedocs' own schema - if it doesn't, that's a
+  // converter bug, and writing it would only hand the author a broken file.
+  const result = validateDocsConfig(text);
+  if (!result.ok) {
+    console.error('[writedocs] The converted writedocs.json is not valid - this is a bug in the converter, please report it:\n');
+    console.error(formatValidationIssuesDetailed(result.issues));
+    console.error(`\n${text}`);
+    process.exit(1);
+  }
+
+  if (dryRun) {
+    console.log(text);
+  } else {
+    fs.writeFileSync(outPath, text);
+    console.log(`[writedocs] Converted ${path.basename(docsJsonPath)} -> ${outPath}`);
+  }
+
+  if (notes.length) {
+    console.log(`\n[writedocs] ${notes.length} thing${notes.length === 1 ? '' : 's'} couldn't be carried over as-is:\n`);
+    console.log(formatNotes(notes));
+  }
+
+  // The pages, checked against the converted config - what's left to fix
+  // before the first build.
+  const content = await checkContent(contentDir, text);
+  if (content.errors.length) {
+    console.log(`\n[writedocs] ${content.errors.length} error${content.errors.length === 1 ? '' : 's'} in the pages - the build would fail on these:\n`);
+    console.log(formatContentIssues(content.errors));
+  }
+  if (content.warnings.length) {
+    console.log(`\n[writedocs] ${content.warnings.length} warning${content.warnings.length === 1 ? '' : 's'} in the pages:\n`);
+    console.log(formatContentIssues(content.warnings));
+  }
+  console.log(
+    `\n[writedocs] Checked ${content.pages} page${content.pages === 1 ? '' : 's'}: ${content.errors.length} error${content.errors.length === 1 ? '' : 's'}, ${content.warnings.length} warning${content.warnings.length === 1 ? '' : 's'}.`
+  );
+  if (!config.domain) {
+    console.log(
+      '[writedocs] 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.)'
+    );
+  }
+}

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

@@ -3,6 +3,8 @@ import path from 'node:path';
 import SwaggerParser from '@apidevtools/swagger-parser';
 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';
 
 const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
 
@@ -99,10 +101,17 @@ function scanDirForOverrides(dir, relBase, overrides) {
     }
     if (!/\.mdx?$/i.test(entry.name)) continue;
     const raw = fs.readFileSync(full, 'utf-8');
-    const { data } = matter(raw);
+    let data;
+    try {
+      ({ data } = matter(raw));
+    } catch {
+      continue; // invalid frontmatter - `writedocs validate` and the build report it
+    }
     if (typeof data.openapi !== 'string') continue;
     const fileId = rel.replace(/\.mdx?$/i, '').replace(/\/index$/, '');
-    overrides.set(data.openapi.trim().replace(/\s+/g, ' '), fileId);
+    // Keyed by "METHOD /path" whichever form the page wrote - Mintlify's
+    // "spec.json METHOD /path" included (see lib/openapi-ref.js).
+    overrides.set(openApiOperationKey(data.openapi) ?? data.openapi.trim().replace(/\s+/g, ' '), fileId);
   }
 }
 
@@ -337,7 +346,6 @@ export async function generateApiPages({ contentDir }) {
   rmrf(openapiOutDir);
 
   const groups = collectOpenApiGroups(config.navigation);
-  if (groups.length === 0) return;
 
   const seenPaths = new Map(); // normalized path -> owning group's label
   for (const group of groups) {
@@ -356,4 +364,49 @@ export async function generateApiPages({ contentDir }) {
   for (const group of groups) {
     await generateApiPagesForGroup({ contentDir, generatedDocsDir, group, overrides });
   }
+
+  await parsePageSpecs({ contentDir, openapiOutDir, groupSpecs: groups.map((g) => path.resolve(contentDir, g.openapi.src)) });
+}
+
+/** Mintlify's page-level form, `openapi: "/spec.json METHOD /path"`: the
+ *  page names its spec itself instead of belonging to an openapi group in
+ *  writedocs.json. Every such spec (that no group already parsed) is parsed
+ *  here and its operations written under openapi/_pages/<spec>/operations/,
+ *  where findOperationFile() (lib/openapi-render.ts) looks for them. No
+ *  pages are generated - the pages that name the spec are the pages. A
+ *  spec that's missing or doesn't parse is a warning, not a build failure:
+ *  its pages show the playground's own "no operation found" notice. */
+async function parsePageSpecs({ contentDir, openapiOutDir, groupSpecs }) {
+  const specs = new Set();
+  for (const rel of findAllPages(contentDir)) {
+    let data;
+    try {
+      ({ data } = matter(fs.readFileSync(path.join(contentDir, rel), 'utf-8')));
+    } catch {
+      continue;
+    }
+    const ref = parseOpenApiRef(data?.openapi);
+    if (ref?.spec) specs.add(ref.spec);
+  }
+  for (const spec of specs) {
+    const specPath = path.resolve(contentDir, spec);
+    if (groupSpecs.includes(specPath)) continue;
+    if (!fs.existsSync(specPath)) {
+      console.warn(`[writedocs] Pages name the OpenAPI spec "${spec}", which doesn't exist - their API playground shows a notice instead.`);
+      continue;
+    }
+    let operations;
+    try {
+      operations = buildOperations(await SwaggerParser.dereference(specPath));
+    } catch (err) {
+      console.warn(`[writedocs] Couldn't parse the OpenAPI spec "${spec}" that pages name: ${err.message}`);
+      continue;
+    }
+    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));
+    }
+    console.log(`[writedocs] Parsed OpenAPI spec "${spec}" for the pages that name it (${operations.length} operations)`);
+  }
 }

package/src/components/Accordion.astro

@@ -1,4 +1,5 @@
 ---
+import { extraClasses } from './class-names';
 import AppIcon from "./AppIcon.astro";
 
 interface Props {
@@ -32,7 +33,7 @@ function slugify(value: string): string {
 const titleId = _titleId ?? slugify(title);
 ---
 
-<details class="wd-accordion" open={defaultOpen}>
+<details class:list={["wd-accordion", extraClasses(Astro.props)]} open={defaultOpen}>
   <summary>
     <span class="wd-accordion-heading">
       {icon && <AppIcon icon={icon} class="wd-accordion-icon" />}

package/src/components/AccordionGroup.astro

@@ -1,4 +1,7 @@
-<div class="wd-accordion-group">
+---
+import { extraClasses } from './class-names';
+---
+<div class:list={["wd-accordion-group", extraClasses(Astro.props)]}>
   <slot />
 </div>
 <style is:global>

package/src/components/ApiPlayground.astro

@@ -12,6 +12,7 @@ import {
   findOperationFile,
   type OpenApiOperation,
 } from '../lib/openapi-render';
+import { parseOpenApiRef } from '../lib/openapi-ref.js';
 
 interface Props {
   operation: string; // "METHOD /path", matching a page's `openapi` frontmatter
@@ -19,8 +20,11 @@ interface Props {
 }
 const { operation, contentDir } = Astro.props as Props;
 
-const [method = '', urlPath = ''] = operation.trim().split(/\s+/, 2);
-const opFile = findOperationFile(contentDir, method, urlPath);
+// "METHOD /path", or Mintlify's "spec.json METHOD /path" - see lib/openapi-ref.js.
+const ref = parseOpenApiRef(operation);
+const method = ref?.method ?? '';
+const urlPath = ref?.path ?? '';
+const opFile = ref ? findOperationFile(contentDir, method, urlPath, ref.spec) : null;
 const op: OpenApiOperation | null = opFile ? JSON.parse(fs.readFileSync(opFile, 'utf-8')) : null;
 
 const pathParams = op?.parameters.filter((p) => p.in === 'path') ?? [];