@writedocs/generator 0.4.8 → 0.4.9

package/astro.config.mjs

@@ -27,6 +27,7 @@ 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 { remarkUnknownComponentFallback } from './src/lib/mdx-unknown-components.js';
 import { writedocsTempDir, writedocsBuildStagingDir } from './src/lib/writedocs-temp-dir.js';
 import { stylesAssetFallback } from './src/lib/styles-asset-integration.js';
 import {
@@ -370,6 +371,11 @@ export default defineConfig({
         // the tree when it looks for components to import.
         remarkMintlifyTreeLists,
         remarkMintlifyPromptText,
+        // 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

package/bin/writedocs.js

@@ -1,139 +1,167 @@
-#!/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('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.9",
   "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/components/AppIcon.astro

@@ -7,7 +7,7 @@
 // and Card.astro (the two places writedocs.json icon strings get rendered)
 // don't each need their own copy of the resolveIcon() call + branch.
 import { Icon } from 'astro-icon/components';
-import { resolveIcon } from '../lib/config';
+import { resolveIcon, iconExists } from '../lib/config';
 
 interface Props {
   icon?: string;
@@ -21,7 +21,19 @@ interface Props {
   style?: string;
 }
 const { icon, class: className = 'wd-icon', style } = Astro.props as Props;
-const resolved = icon ? resolveIcon(icon) : null;
+// An icon name no installed collection has renders nothing, with a warning
+// (once per name - a sidebar icon renders on every page), instead of
+// failing the whole build the way astro-icon does on a missing name.
+// `writedocs validate` lists the same names ahead of time.
+let resolved = icon ? resolveIcon(icon) : null;
+if (icon && resolved?.kind === 'iconify' && !iconExists(icon)) {
+  const warned: Set<string> = ((globalThis as any).__wdWarnedIcons ??= new Set());
+  if (!warned.has(icon)) {
+    warned.add(icon);
+    console.warn(`[writedocs] unknown icon "${icon}" - no installed icon set has it, so it's left out.`);
+  }
+  resolved = null;
+}
 ---
 {resolved && (
   resolved.kind === 'iconify' ? (

package/src/content.config.ts

@@ -1,11 +1,10 @@
 import { defineCollection } from 'astro:content';
 import { glob } from 'astro/loaders';
 import type { Loader } from 'astro/loaders';
-import { z } from 'astro/zod';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
-import { seoFieldsSchema, findAllPages } from './lib/config';
+import { pageFrontmatterSchema, findAllPages } from './lib/config';
 import { writedocsTempDir } from './lib/writedocs-temp-dir.js';
 
 const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
@@ -32,131 +31,11 @@ const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
 const generatedDocsDir = path.join(writedocsTempDir(contentDir), 'generated-docs');
 const generatedDocsBase = pathToFileURL(generatedDocsDir + path.sep);
 
-const MINTLIFY_MODE_ALIASES: Record<string, string> = { center: 'frame', assistant: 'default' };
-
-const docsSchema = z.object({
-  title: z.string(),
-  description: z.string().optional(),
-  // Overrides the URL this page is served at, independent of where the
-  // file actually lives - writedocs.json's `pages` arrays always keep
-  // referencing the file's own path regardless. This is Astro's own
-  // glob()-loader convention (a `slug` frontmatter field becomes
-  // `entry.id` verbatim - see generateIdDefault in
-  // astro/dist/content/loaders/glob.js), not writedocs-specific
-  // behavior; declaring it here just brings it into the schema (and
-  // its docs) rather than leaving it an undocumented Astro feature.
-  // See fileIdForEntry() in lib/config.ts for how routes/links still
-  // resolve a page by its file id once this diverges from `entry.id`.
-  // Leading/trailing slashes are fine either way ("/", "/guides/x",
-  // "guides/x" and "guides/x/" all mean the same thing) - see
-  // normalizeEntryId() in lib/config.ts, which is what actually
-  // strips them before this value is ever used as a route or href.
-  slug: z.string().optional(),
-  // Marks this page as an OpenAPI operation reference: "METHOD /path"
-  // matching an operation in the owning group's OpenAPI spec, e.g.
-  // "GET /pets/{petId}" - [...slug].astro renders <ApiPlayground /> for
-  // any page with this field set, below the page's own MDX body (if
-  // any). Sites don't write this by hand for most pages; it's either
-  // set on a generated stub in the `generatedDocs` collection below (see
-  // generate-api-pages.js) or hand-authored to "eject" one specific
-  // operation into a real file (in `docs`) with custom prose - either
-  // way, the value is always exactly the same "METHOD /path" key
-  // generate-api-pages.js uses to look up the operation's full resolved
-  // schema/examples at render time.
-  openapi: z.string().optional(),
-  // Controls how much of the site's own chrome (topbar, sidebar, table of
-  // contents) wraps this page - see BaseLayout.astro/[...slug].astro for
-  // what each value actually removes:
-  //   default - the normal three-column reading layout (all chrome).
-  //   wide    - drops the table of contents; the article itself also
-  //             renders wider, for content that wants the extra room
-  //             (wide tables, side-by-side images).
-  //   frame   - drops the sidebar and table of contents, but keeps the
-  //             topbar and the article's own normal presentation
-  //             ("frame" as in: still inside the site's outer frame).
-  //   custom  - drops the sidebar and table of contents, the
-  //             auto-rendered <h1>, and prev/next nav, and skips the
-  //             article's own prose width/padding too - a blank canvas
-  //             for a hand-built landing/home page made entirely of
-  //             components - but keeps the topbar, so the page still
-  //             has site branding/nav/search/theme-toggle available.
-  //   blank   - everything 'custom' drops, plus the topbar too: no site
-  //             chrome at all, just <slot />. For a page that wants to
-  //             look nothing like the rest of the site (an auth screen,
-  //             a print-style page).
-  //
-  // Two Mintlify values are accepted so a migrated page doesn't fail the
-  // build (see MINTLIFY_MODE_ALIASES below): `center` is the same layout
-  // as our `frame`, and `assistant` (a full-page Mintlify AI chat, which
-  // writedocs doesn't have) falls back to `default`. Mintlify's own
-  // `frame` means something else (a canvas that keeps the sidebar) - it's
-  // left as our `frame`; see docs/dev/docs/mintlify-compat.mdx.
-  mode: z
-    .preprocess(
-      (value) => (typeof value === 'string' && value in MINTLIFY_MODE_ALIASES ? MINTLIFY_MODE_ALIASES[value] : value),
-      z.enum(['default', 'wide', 'frame', 'custom', 'blank']),
-    )
-    .default('default'),
-  // Per-page meta tag overrides - same shape as writedocs.json's top-level
-  // `seo` (see seoFieldsSchema in lib/config.ts, the single source of
-  // truth for this shape). A page only needs to set the specific fields
-  // it wants to override; mergeSeo() falls back to the site-wide default
-  // for anything left unset. See BaseLayout.astro for where this and the
-  // site-wide seo actually get merged and rendered.
-  seo: seoFieldsSchema.optional(),
-  // Mintlify's spelling of `seo.noindex` - a top-level `noindex: true`.
-  // Folded into `seo` by the transform below, so everything downstream
-  // (the robots meta tag, sitemap.xml, llms.txt) keeps reading
-  // `seo.noindex` only.
-  noindex: z.boolean().optional(),
-  // Mintlify's short navigation label - used for the sidebar and the
-  // topbar dropdown menus in place of `title` ([...slug].astro's
-  // navTitleForSlug). The page's own <h1> and prev/next links keep `title`.
-  sidebarTitle: z.string().optional(),
-  // Mintlify's spellings of `seo.keywords`, `seo.ogImage`, `seo.ogType`
-  // and `seo.twitterCard`, folded into `seo` below like `noindex`.
-  keywords: z.array(z.string()).optional(),
-  'og:image': z.string().optional(),
-  'og:type': z.string().optional(),
-  'twitter:card': z.enum(['summary', 'summary_large_image']).optional(),
-  // Mintlify's sidebar/page-chrome fields - see NavTree.astro and
-  // [...slug].astro for where each is used:
-  //   icon                 - shown before the page's label in the sidebar.
-  //   tag                  - a short label after it (e.g. "NEW").
-  //   deprecated           - a "Deprecated" label in the sidebar and next
-  //                          to the page's <h1>.
-  //   hidden               - left out of the sidebar, dropdowns and
-  //                          prev/next, but still built and reachable by
-  //                          URL. Also noindexed, as on Mintlify.
-  //   url                  - an external link: the page's sidebar entry
-  //                          links straight to it, and the page's own URL
-  //                          redirects there.
-  //   hideFooterPagination - no prev/next links on this page.
-  //   hideApiMarker        - no HTTP method badge on this page's sidebar
-  //                          entry.
-  icon: z.string().optional(),
-  tag: z.string().optional(),
-  deprecated: z.boolean().optional(),
-  hidden: z.boolean().optional(),
-  url: z.string().optional(),
-  hideFooterPagination: z.boolean().optional(),
-  hideApiMarker: z.boolean().optional(),
-}).transform(
-  ({ noindex, keywords, 'og:image': ogImage, 'og:type': ogType, 'twitter:card': twitterCard, ...data }) => {
-    // Top-level Mintlify keys fill in `seo` only where the page's own `seo`
-    // doesn't already set that field - an explicit `seo` value always wins.
-    // A `hidden` page is noindexed unless it says otherwise.
-    const fromMintlify = { noindex: noindex ?? (data.hidden ? true : undefined), keywords, ogImage, ogType, twitterCard };
-    const seo = { ...data.seo };
-    let changed = false;
-    for (const [key, value] of Object.entries(fromMintlify)) {
-      if (value === undefined || seo[key as keyof typeof seo] !== undefined) continue;
-      (seo as Record<string, unknown>)[key] = value;
-      changed = true;
-    }
-    return changed ? { ...data, seo } : data;
-  },
-);
+// Page frontmatter - defined in lib/config-schema.ts as
+// pageFrontmatterSchema, next to writedocs.json's own schema, so
+// `writedocs validate` checks every page against exactly the schema the
+// build uses (that file compiles to the plain JS validate loads).
+const docsSchema = pageFrontmatterSchema;
 
 /** Wraps another loader so it's skipped entirely - no filesystem scan, no
  *  "directory doesn't exist"/"no files found" warning - when its own base