@writedocs/generator 0.6.0 → 0.7.0

package/src/lib/json-schema.js

@@ -0,0 +1,91 @@
+// writedocs.schema.json - the JSON Schema of writedocs.json, for editors
+// (autocompletion, hover help, red squiggles). Generated from the Zod
+// schema itself (config-schema.ts, through its generated .js) rather than
+// written by hand, so it accepts exactly what `writedocs validate` and the
+// build accept. The help text comes from json-schema-descriptions.js.
+//
+// scripts/build-json-schema.mjs writes it to the package root (run by
+// `prepare`); scripts/json-schema.test.js checks it against real configs.
+import { z } from 'zod';
+import { docsConfigSchema } from './config-schema.js';
+import { DESCRIPTIONS, TYPE_DESCRIPTIONS, ROOT_DESCRIPTION } from './json-schema-descriptions.js';
+
+// Zod names the navigation's recursive types __schema0, __schema1, ... -
+// given their real names here, recognized by the field that identifies
+// each one.
+const TYPE_BY_KEY = { tab: 'Tab', version: 'Version', language: 'Language', dropdown: 'Dropdown', product: 'Product' };
+
+function typeNameFor(definition) {
+  const variants = definition.anyOf ?? [definition];
+  if (variants.some((v) => v.type === 'string')) return 'NavigationItem';
+  const keys = Object.keys(variants[0]?.properties ?? {});
+  const key = keys.find((k) => TYPE_BY_KEY[k]);
+  return key ? TYPE_BY_KEY[key] : null;
+}
+
+function renameDefinitions(schema) {
+  const renames = {};
+  for (const [name, definition] of Object.entries(schema.definitions ?? {})) {
+    const readable = typeNameFor(definition);
+    if (readable) renames[name] = readable;
+  }
+  const text = JSON.stringify(schema).replace(/"#\/definitions\/([^"]+)"/g, (m, name) => `"#/definitions/${renames[name] ?? name}"`);
+  const renamed = JSON.parse(text);
+  renamed.definitions = Object.fromEntries(Object.entries(renamed.definitions ?? {}).map(([name, d]) => [renames[name] ?? name, d]));
+  return renamed;
+}
+
+/** Calls `visit(propertySchema, path)` for every property, through unions
+ *  and array items (not through $refs - definitions are walked on their own
+ *  with the type name as the path's start). */
+function eachProperty(node, path, visit) {
+  if (!node || typeof node !== 'object') return;
+  for (const [key, child] of Object.entries(node.properties ?? {})) {
+    const childPath = path ? `${path}.${key}` : key;
+    visit(child, childPath);
+    eachProperty(child, childPath, visit);
+  }
+  if (node.items) eachProperty(node.items, `${path}[]`, visit);
+  for (const key of ['anyOf', 'oneOf', 'allOf']) for (const variant of node[key] ?? []) eachProperty(variant, path, visit);
+}
+
+function describe(target, text) {
+  target.description = text;
+  // VS Code renders this one, with `code` formatting.
+  target.markdownDescription = text;
+}
+
+/** { schema, undocumented, unused } - `undocumented`: field paths with no
+ *  description; `unused`: descriptions for paths that don't exist. */
+export function buildJsonSchema() {
+  let schema = z.toJSONSchema(docsConfigSchema, { io: 'input', target: 'draft-7', unrepresentable: 'any' });
+  schema = renameDefinitions(schema);
+
+  // `$schema` is the one extra key writedocs.json accepts (see
+  // ROOT_ALLOWED_EXTRA_KEYS); every other unknown key is a typo the build
+  // would ignore, so the editor flags it.
+  schema.properties = { $schema: { type: 'string' }, ...schema.properties };
+  schema.additionalProperties = false;
+
+  const seen = new Set();
+  const undocumented = [];
+  const apply = (node, path) => {
+    seen.add(path);
+    if (DESCRIPTIONS[path]) describe(node, DESCRIPTIONS[path]);
+    else if (!undocumented.includes(path)) undocumented.push(path);
+  };
+  eachProperty(schema, '', apply);
+  for (const [name, definition] of Object.entries(schema.definitions ?? {})) {
+    if (TYPE_DESCRIPTIONS[name]) describe(definition, TYPE_DESCRIPTIONS[name]);
+    eachProperty(definition, name, apply);
+  }
+  const unused = Object.keys(DESCRIPTIONS).filter((path) => !seen.has(path));
+
+  const ordered = {
+    $schema: schema.$schema,
+    title: 'writedocs.json',
+    description: ROOT_DESCRIPTION,
+    ...Object.fromEntries(Object.entries(schema).filter(([key]) => key !== '$schema')),
+  };
+  return { schema: ordered, undocumented, unused };
+}

package/src/lib/link-check.js

@@ -76,6 +76,27 @@ function normalizeEntryId(id) {
 }
 const urlForId = (id) => (id === 'index' ? '/' : `/${id}/`);
 
+/** (rel, frontmatterSlug) => the URL the build serves that page at: its
+ *  frontmatter `slug`, or its file path with each segment through
+ *  github-slugger (see this file's header). Also used by
+ *  lib/writedocs-legacy-convert.js, for redirects from old addresses. */
+export async function pageUrlResolver() {
+  const { slug } = await loadSlugger();
+  return (rel, frontmatterSlug) =>
+    urlForId(
+      frontmatterSlug
+        ? normalizeEntryId(frontmatterSlug)
+        : normalizeEntryId(
+            rel
+              .replace(/\.mdx?$/i, '')
+              .split('/')
+              .map((segment) => slug(segment))
+              .join('/')
+              .replace(/\/index$/, '')
+          )
+    );
+}
+
 function textOf(node) {
   if (typeof node.value === 'string' && (node.type === 'text' || node.type === 'inlineCode')) return node.value;
   return (node.children ?? []).map(textOf).join('');
@@ -246,6 +267,7 @@ function configLinks(config) {
  */
 export async function checkLinks(contentDir, configText) {
   const { slug, default: Slugger } = await loadSlugger();
+  const urlOf = await pageUrlResolver();
   const config = JSON.parse(configText);
 
   // --- What the site has -------------------------------------------------
@@ -260,17 +282,7 @@ export async function checkLinks(contentDir, configText) {
   for (const rel of pageFiles) {
     const abs = path.join(contentDir, rel);
     const scan = await scanOnce(abs);
-    const id = scan?.data?.slug
-      ? normalizeEntryId(scan.data.slug)
-      : normalizeEntryId(
-          rel
-            .replace(/\.mdx?$/i, '')
-            .split('/')
-            .map((segment) => slug(segment))
-            .join('/')
-            .replace(/\/index$/, '')
-        );
-    const url = urlForId(id);
+    const url = urlOf(rel, scan?.data?.slug);
     pages.set(url, { rel, abs, scan });
     urlOfFile.set(rel, url);
   }

package/src/lib/mintlify-convert.js

@@ -57,7 +57,7 @@ function pathString(trail) {
   return trail.reduce((s, part) => (typeof part === 'number' ? `${s}[${part}]` : s ? `${s}.${part}` : part), '');
 }
 
-class Notes {
+export class Notes {
   constructor() {
     this.byKey = new Map();
   }
@@ -83,7 +83,7 @@ const ENDPOINT_RE = /^(?:(\S+?\.(?:json|ya?ml))\s+)?(GET|POST|PUT|PATCH|DELETE|H
 // item that isn't in that item type's own list below is reported.
 const STRUCTURAL = ['pages', 'groups', 'tabs', 'anchors', 'dropdowns', 'products', 'versions', 'languages', 'menu', 'href', 'openapi', 'hidden'];
 
-const LANGUAGE_NAMES = {
+export const LANGUAGE_NAMES = {
   ar: 'العربية', ca: 'Català', cn: '简体中文', 'zh-Hant': '繁體中文', cs: 'Čeština', da: 'Dansk', de: 'Deutsch',
   en: 'English', es: 'Español', fi: 'Suomi', fr: 'Français', 'fr-CA': 'Français (Canada)', he: 'עברית',
   hi: 'हिन्दी', hu: 'Magyar', id: 'Bahasa Indonesia', it: 'Italiano', ja: '日本語', 'ja-JP': '日本語', jp: '日本語',

package/src/lib/writedocs-legacy-convert.js

@@ -0,0 +1,496 @@
+// Converts the previous writedocs' config.json (the Docusaurus-based
+// generator, https://docs.writedocs.io/schema.json) into a writedocs.json -
+// `writedocs convert --writedocs` (src/cli/convert.js). Plain JavaScript, so
+// the CLI can load it from an installed package.
+//
+// Unlike Mintlify's docs.json, config.json doesn't say where a page lives:
+// pages are ids resolved against the docs/ folder the way the old
+// generator's sidebar builder did (docusaurus-template/writedocs/
+// sidebar.config.js) - `Guides/Setup/intro` is docs/Guides/Setup/intro.mdx
+// (or .api.mdx / .info.mdx), a leading "docs/" and an extension are
+// ignored, and a page whose file name starts with "_" was hidden. So the
+// conversion reads the project folder, not just the file: it checks each
+// page exists, reads its frontmatter for its old address, and finds the
+// OpenAPI specs.
+//
+// Only config.json is converted - pages are left as they are.
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { iconExists } from './icons.js';
+import { fileIdForPath } from './pages.js';
+import { Notes, LANGUAGE_NAMES } from './mintlify-convert.js';
+import { pageUrlResolver } from './link-check.js';
+
+export function loadLegacyConfig(file) {
+  return JSON.parse(fs.readFileSync(file, 'utf-8'));
+}
+
+const PAGE_ENDINGS = ['.api.mdx', '.info.mdx', '.mdx', '.md'];
+// Keys config.json had that are about the old platform itself, not the site.
+const PLATFORM_KEYS = new Set(['$schema', 'dashboard', 'draftStructures']);
+const HANDLED_KEYS = new Set([
+  'websiteName', 'description', 'homepage', 'images', 'styles', 'colorMode', 'navbar', 'sidebars', 'apiFiles',
+  'apiOptions', 'translatedApiFiles', 'codeLanguages', 'changelog', 'externalLinks', 'integrations', 'footer',
+  'languages', 'hideWatermark', 'protected', 'closeSubpages',
+]);
+
+const nonEmpty = (v) => typeof v === 'string' && v.trim() !== '';
+const isUrl = (v) => /^[a-z][a-z0-9+.-]*:\/\//i.test(String(v));
+const posix = (p) => p.split(path.sep).join('/');
+
+/** An image path from config.json as a writedocs path: relative paths
+ *  ("media/logo.png") were relative to the project root, so they get a
+ *  leading slash; URLs stay as they are. */
+function assetPath(value) {
+  if (!nonEmpty(value)) return undefined;
+  const v = value.trim();
+  return isUrl(v) || v.startsWith('/') ? v : `/${v.replace(/^\.\//, '')}`;
+}
+
+/** A Phosphor icon name (the old navbar's icon set, "BookOpen") as the
+ *  Lucide name writedocs uses, when Lucide has one. */
+function convertIcon(name) {
+  if (!nonEmpty(name)) return undefined;
+  const kebab = name.trim().replace(/([a-z0-9])([A-Z])/g, '$1-$2').replace(/([A-Z])([A-Z][a-z])/g, '$1-$2').toLowerCase();
+  if (iconExists(kebab)) return kebab;
+  return null;
+}
+
+/** The page id as the old generator cleaned it (cleanPath() in its
+ *  sidebar.config.js). */
+function cleanId(id) {
+  return String(id)
+    .trim()
+    .replace(/^\/?docs\//, '')
+    .replace(/^\//, '')
+    .replace(/(\.endpoint)?(\.(md|mdx))?$/, '');
+}
+
+export async function convertLegacyConfig(old, contentDir) {
+  const notes = new Notes();
+  const urlOf = await pageUrlResolver();
+  const config = {};
+
+  // The first language is the default one; config.json's pages are in it.
+  const languages = Array.isArray(old.languages) && old.languages.filter(nonEmpty).length ? old.languages.filter(nonEmpty) : ['en'];
+
+  // --- Pages ---------------------------------------------------------------
+  const pageCache = new Map();
+  /** { rel, id, data } for the file a page id names under `base` (docs/,
+   *  or a language's folder), or null. */
+  function findPage(id, base = 'docs') {
+    const key = `${base}\n${id}`;
+    if (pageCache.has(key)) return pageCache.get(key);
+    let found = null;
+    const clean = cleanId(id);
+    for (const ending of PAGE_ENDINGS) {
+      const rel = `${base}/${clean}${ending}`;
+      const abs = path.join(contentDir, rel);
+      if (!fs.existsSync(abs)) continue;
+      let data = {};
+      try {
+        data = matter(fs.readFileSync(abs, 'utf-8'), {}).data ?? {};
+      } catch {}
+      found = { rel, id: fileIdForPath(rel), clean, data };
+      break;
+    }
+    pageCache.set(key, found);
+    return found;
+  }
+  const hiddenPage = (id) => cleanId(id).split('/').pop().startsWith('_');
+
+  // --- OpenAPI specs ---------------------------------------------------------
+  // apiFiles: a spec path (relative to openAPI/) or URL, or { file,
+  // outputDir }. The old generator wrote a spec's pages to outputDir, by
+  // default docs/reference/<spec name> - which is where sidebar ids like
+  // "reference/pets/list-pets" pointed.
+  const specs = (Array.isArray(old.apiFiles) ? old.apiFiles : [])
+    .map((entry, i) => {
+      const file = typeof entry === 'string' ? entry : entry?.file;
+      if (!nonEmpty(file)) return null;
+      const name = path.parse(file.split('?')[0]).name;
+      const outputDir = (typeof entry === 'object' && nonEmpty(entry.outputDir) ? entry.outputDir : `docs/reference/${name.replace('_', '-')}`)
+        .replace(/^\.?\//, '')
+        .replace(/\/+$/, '');
+      const prefix = outputDir.replace(/^docs\//, '');
+      if (isUrl(file)) return { i, file, remote: true, prefix };
+      const candidates = [file.startsWith('openAPI/') ? file : `openAPI/${file}`, file];
+      const src = candidates.find((c) => fs.existsSync(path.join(contentDir, c)));
+      return { i, file, src: src ? posix(src) : null, prefix };
+    })
+    .filter(Boolean);
+  for (const spec of specs) {
+    if (spec.remote) {
+      notes.add(`spec-remote-${spec.i}`, ['apiFiles', spec.i], `The OpenAPI spec ${spec.file} is a URL - writedocs reads specs from the project.`, 'Download it into the project (openAPI/ is fine), and its API pages come back - see the note on the API pages below.');
+    } else if (!spec.src) {
+      notes.add(`spec-missing-${spec.i}`, ['apiFiles', spec.i], `The OpenAPI spec ${spec.file} isn't in the project (looked in openAPI/ and the project folder).`);
+    }
+  }
+  const usedSpecs = new Set();
+  const apiPaths = new Set();
+
+  /** The spec a category of generated API pages came from: the one whose
+   *  output folder the page ids are in, or the only spec there is. */
+  function specFor(ids) {
+    const byPrefix = specs.find((s) => ids.every((id) => cleanId(id).startsWith(`${s.prefix}/`)));
+    if (byPrefix) return { ...byPrefix, urlPrefix: byPrefix.prefix };
+    if (specs.length !== 1) return null;
+    // Matched by elimination: the pages' own folder is the better address.
+    const folders = ids.map((id) => cleanId(id).split('/').slice(0, -1).join('/'));
+    const common = folders.reduce((a, b) => {
+      const x = a.split('/');
+      const y = b.split('/');
+      let n = 0;
+      while (n < x.length && x[n] === y[n]) n += 1;
+      return x.slice(0, n).join('/');
+    });
+    return { ...specs[0], urlPrefix: common || specs[0].prefix };
+  }
+
+  // --- Sidebars ------------------------------------------------------------
+  const translations = readTranslations(contentDir);
+  const redirects = new Map(); // old URL -> new URL
+  const pageUrls = new Set();
+  const missing = []; // { id, trail }
+
+  /** Every page id items name - groups' own `page` included. */
+  const idsIn = (items) =>
+    (items ?? []).flatMap((item) => (typeof item === 'string' ? [item] : [item?.page, ...idsIn(item?.subpages)].filter(Boolean)));
+  /** The page ids in items that aren't a group's own `page`. */
+  const leafIds = (items) => (items ?? []).flatMap((item) => (typeof item === 'string' ? [item] : leafIds(item?.subpages)));
+
+  /** The URL path a spec's generated pages go under: its old output
+   *  folder ("reference/pets"), or the folder its pages' ids were in.
+   *  Each OpenAPI group needs its own. */
+  function apiPathFor(spec, ctx) {
+    const prefix = spec.urlPrefix || 'reference';
+    let base = `/${prefix}`;
+    for (let n = 2; apiPaths.has(`${ctx.lang}\n${base}`); n += 1) base = `/${prefix}-${n}`;
+    apiPaths.add(`${ctx.lang}\n${base}`);
+    return ctx.lang === ctx.defaultLang ? base : `/${ctx.lang}${base}`;
+  }
+
+  function convertItems(items, ctx, trail) {
+    const out = [];
+    (items ?? []).forEach((item, i) => {
+      if (typeof item === 'string') {
+        const page = resolve(item, ctx, [...trail, i]);
+        if (page) out.push(page);
+        return;
+      }
+      if (!item || typeof item !== 'object') return;
+      const group = { group: ctx.label(item.groupName ?? 'Untitled group') };
+      if (item.page && !hiddenPage(item.page)) {
+        const page = resolve(item.page, ctx, [...trail, i, 'page']);
+        if (page) group.page = page;
+      }
+      group.pages = convertItems(item.subpages, ctx, [...trail, i, 'subpages']);
+      if (group.page || group.pages.length) out.push(group);
+    });
+    return out;
+  }
+
+  /** A page id as the page's writedocs id (in the current language, when a
+   *  translation exists), recording its old address for a redirect. */
+  function resolve(id, ctx, trail) {
+    if (hiddenPage(id)) return null;
+    const page = findPage(id);
+    if (!page) {
+      if (ctx.lang === ctx.defaultLang) missing.push({ id, trail });
+      return null;
+    }
+    if (ctx.lang === ctx.defaultLang) recordAddress(page);
+    if (ctx.lang !== ctx.defaultLang) {
+      const translated = findPage(page.clean, `translations/${ctx.lang}`) ?? findPage(page.clean, `i18n/${ctx.lang}/docusaurus-plugin-content-docs/current`);
+      if (translated) return translated.id;
+    }
+    return page.id;
+  }
+
+  /** The address the old site served a page at: its frontmatter `slug`
+   *  (absolute, or relative to its folder), or its id path - with a
+   *  frontmatter `id` replacing the file name, and an index file standing
+   *  for its folder (Docusaurus' rules). */
+  function recordAddress(page) {
+    const newUrl = urlOf(page.rel, page.data.slug);
+    pageUrls.add(newUrl);
+    const folder = page.clean.split('/').slice(0, -1);
+    let oldPath;
+    if (nonEmpty(page.data.slug)) {
+      oldPath = page.data.slug.startsWith('/') ? page.data.slug : `/${[...folder, page.data.slug].join('/')}`;
+    } else {
+      const last = nonEmpty(page.data.id) ? page.data.id : page.clean.split('/').pop().replace(/\.(api|info)$/, '');
+      oldPath = `/${(last.toLowerCase() === 'index' ? folder : [...folder, last]).join('/')}`;
+    }
+    const oldUrl = oldPath.replace(/\/+$/, '') || '/';
+    if (`${oldUrl}/`.replace(/\/\/$/, '/') === newUrl) return;
+    redirects.set(oldUrl, newUrl);
+  }
+
+  function convertCategories(categories, ctx, trail) {
+    const groups = [];
+    (categories ?? []).forEach((category, i) => {
+      const categoryTrail = [...trail, i];
+      // A category of generated API pages - its pages aren't files in the
+      // project, they came from a spec - becomes an OpenAPI group, once per
+      // spec. Groups in it can open on a hand-written page (a tag's intro);
+      // those are kept, above the generated ones.
+      const leaves = leafIds(category?.pages);
+      if (leaves.length && leaves.every((id) => !findPage(id))) {
+        const spec = specFor(leaves);
+        if (spec) {
+          const name = ctx.label(category?.categoryName ?? 'API Reference');
+          if (ctx.lang === ctx.defaultLang) {
+            notes.add(`api-${spec.i}`, categoryTrail, `These API pages were generated from ${spec.file}; they're an OpenAPI group now - a page for every operation in the spec, grouped by tag.`);
+          }
+          const intros = idsIn(category?.pages)
+            .filter((id) => !leaves.includes(id))
+            .map((id, n) => resolve(id, ctx, [...categoryTrail, 'pages', n]))
+            .filter(Boolean);
+          const key = `${ctx.lang}\n${spec.i}`;
+          const openapi = spec.src && !usedSpecs.has(key) ? { src: spec.src, path: apiPathFor(spec, ctx) } : null;
+          if (openapi) usedSpecs.add(key);
+          const inner = /^endpoints$/i.test(String(category?.categoryName ?? '').trim()) ? 'All endpoints' : 'Endpoints';
+          if (intros.length && openapi) groups.push({ group: name, pages: [...intros, { group: ctx.label(inner), openapi }] });
+          else if (intros.length) groups.push({ group: name, pages: intros });
+          else if (openapi) groups.push({ group: name, openapi });
+          return;
+        }
+      }
+      const pages = convertItems(category?.pages, ctx, [...categoryTrail, 'pages']);
+      if (pages.length) groups.push({ group: ctx.label(category?.categoryName ?? 'Untitled'), pages });
+    });
+    return groups;
+  }
+
+  const sidebars = new Map((Array.isArray(old.sidebars) ? old.sidebars : []).map((s, i) => [s?.sidebarRef, { sidebar: s, i }]));
+  const usedSidebars = new Set();
+
+  /** A sidebar's content, as a container's children: `pages`, or
+   *  `versions` when the sidebar has versions. */
+  function sidebarContent(ref, ctx, apiLabel) {
+    const entry = sidebars.get(ref);
+    if (!entry) return null;
+    usedSidebars.add(ref);
+    const { sidebar, i } = entry;
+    const sctx = { ...ctx, sidebarRef: ref, apiLabel, label: (text) => ctx.translate('sidebars', text, ref) };
+    if (Array.isArray(sidebar.versions) && sidebar.versions.length) {
+      const versions = sidebar.versions
+        .map((v, vi) => ({ version: String(v.version ?? `v${vi + 1}`), pages: convertCategories(v.categories, sctx, ['sidebars', i, 'versions', vi, 'categories']) }))
+        .filter((v) => v.pages.length);
+      return versions.length ? { versions } : null;
+    }
+    const pages = convertCategories(sidebar.categories, sctx, ['sidebars', i, 'categories']);
+    return pages.length ? { pages } : null;
+  }
+
+  function buildNavigation(lang) {
+    const ctx = {
+      lang,
+      defaultLang: languages[0],
+      translate: (section, text, ref) => {
+        if (lang === languages[0] || !translations[lang]) return text;
+        const table = section === 'navbar' ? translations[lang].navbar : translations[lang].sidebars?.[ref];
+        return (table && nonEmpty(table[text]) && table[text]) || text;
+      },
+    };
+    const tabs = [];
+    const navbar = Array.isArray(old.navbar) ? old.navbar : [];
+    navbar.forEach((item, i) => {
+      if (!item || typeof item !== 'object') return;
+      const tab = { tab: ctx.translate('navbar', String(item.label ?? `Tab ${i + 1}`)) };
+      if (item.icon) {
+        const icon = convertIcon(item.icon);
+        if (icon) tab.icon = icon;
+        else if (lang === languages[0]) {
+          notes.add('icon', ['navbar', i, 'icon'], `Icon "${item.icon}" (Phosphor) has no match in writedocs' icon sets - left out.`, 'Add an `icon` to the tab: a Lucide name like "book-open" (lucide.dev), or "collection:name".');
+        }
+      }
+      if (nonEmpty(item.sidebarRef)) {
+        const content = sidebarContent(item.sidebarRef, ctx, item.label);
+        if (content) tabs.push({ ...tab, ...content });
+        else if (lang === languages[0]) notes.add(`tab-empty-${i}`, ['navbar', i], `"${item.label}" points at sidebar "${item.sidebarRef}", which ${sidebars.has(item.sidebarRef) ? 'has no pages that exist' : "doesn't exist"} - left out.`);
+      } else if (Array.isArray(item.dropdown)) {
+        const dropdowns = [];
+        item.dropdown.forEach((d, di) => {
+          const dropdown = { dropdown: ctx.translate('navbar', String(d?.label ?? `Menu ${di + 1}`)) };
+          if (nonEmpty(d?.sidebarRef)) {
+            const content = sidebarContent(d.sidebarRef, ctx, d.label);
+            if (content) dropdowns.push({ ...dropdown, ...content });
+            else if (lang === languages[0]) notes.add(`dd-empty-${i}-${di}`, ['navbar', i, 'dropdown', di], `"${d.label}" points at sidebar "${d.sidebarRef}", which has no pages that exist - left out.`);
+          } else if (nonEmpty(d?.link)) dropdowns.push({ ...dropdown, href: d.link });
+        });
+        if (dropdowns.length) tabs.push({ ...tab, dropdowns });
+        if (lang === languages[0]) notes.add('dropdown', ['navbar', i, 'dropdown'], 'A navbar dropdown became a tab with a dropdown in its sidebar, one entry per sidebar it listed.');
+      } else if (nonEmpty(item.link)) {
+        tabs.push({ ...tab, href: item.link });
+      }
+    });
+    // No navbar (or nothing usable in it): the first sidebar is the site.
+    if (tabs.length === 0) {
+      const first = [...sidebars.keys()][0];
+      const content = first === undefined ? null : sidebarContent(first, ctx, undefined);
+      if (content?.pages) return content.pages;
+      return content ?? [];
+    }
+    // One tab showing a sidebar: a plain list of groups, no tab bar.
+    if (tabs.length === 1 && tabs[0].pages) return tabs[0].pages;
+    return { tabs };
+  }
+
+  // --- Site ------------------------------------------------------------------
+  config.name = nonEmpty(old.websiteName) ? old.websiteName : path.basename(contentDir);
+  if (!nonEmpty(old.websiteName)) notes.add('name', ['websiteName'], `No websiteName - the site is named "${config.name}", after its folder.`);
+  if (nonEmpty(old.description)) config.description = old.description;
+
+  const styles = {};
+  const images = old.images ?? {};
+  const oldStyles = old.styles ?? {};
+  const colors = {};
+  if (nonEmpty(oldStyles.mainColor)) colors.primary = oldStyles.mainColor;
+  if (nonEmpty(oldStyles.darkModeMainColor) && oldStyles.darkModeMainColor !== oldStyles.mainColor) colors.dark = { primary: oldStyles.darkModeMainColor };
+  if (Object.keys(colors).length) styles.colors = colors;
+  const logo = assetPath(images.logo);
+  const darkLogo = assetPath(images.darkLogo);
+  if (logo && darkLogo && darkLogo !== logo) styles.logo = { light: logo, dark: darkLogo };
+  else if (logo || darkLogo) styles.logo = logo ?? darkLogo;
+  if (assetPath(images.favicon)) styles.favicon = assetPath(images.favicon);
+  const navbar = {};
+  if (nonEmpty(oldStyles.navbarColor)) navbar.light = oldStyles.navbarColor;
+  if (nonEmpty(oldStyles.navbarDarkModeColor)) navbar.dark = oldStyles.navbarDarkModeColor;
+  if (Object.keys(navbar).length) styles.navbar = navbar;
+  else if (colors.primary) notes.add('navbar-color', ['styles', 'navbarColor'], 'Without navbarColor, the old navbar used mainColor. writedocs\' topbar matches the page background instead.', `To keep the colored bar, set "styles": { "navbar": { "light": "${colors.primary}" } }.`);
+  const background = {};
+  if (nonEmpty(oldStyles.backgroundDarkModeColor)) background.colors = { dark: oldStyles.backgroundDarkModeColor };
+  const bgLight = assetPath(images.background);
+  // darkBackground: unset means "same as background"; null turned it off.
+  const bgDark = images.darkBackground === null ? undefined : assetPath(images.darkBackground) ?? bgLight;
+  if (bgLight || bgDark) background.images = { ...(bgLight ? { light: bgLight } : {}), ...(bgDark ? { dark: bgDark } : {}) };
+  if (Object.keys(background).length) styles.background = background;
+  if (Object.keys(styles).length) config.styles = styles;
+
+  for (const key of ['logoSize', 'navbarMode']) {
+    if (oldStyles[key] !== undefined) notes.add(`style-${key}`, ['styles', key], `styles.${key} has no writedocs equivalent - dropped.`, key === 'logoSize' ? 'The logo is sized to the topbar\'s height.' : undefined);
+  }
+  if (oldStyles.pagination === false) notes.add('pagination', ['styles', 'pagination'], 'Previous/next links at the bottom of pages are always on in writedocs.', 'To hide them on a page, add `hideFooterPagination: true` to its frontmatter.');
+  if (old.colorMode && (old.colorMode.default === 'dark' || old.colorMode.switchOff)) {
+    notes.add('colorMode', ['colorMode'], 'writedocs follows the reader\'s system theme and always shows the light/dark toggle - colorMode has no equivalent.');
+  }
+
+  // --- Navigation ---------------------------------------------------------
+  const navigations = languages.map((lang) => buildNavigation(lang));
+  if (languages.length > 1) {
+    config.navigation = {
+      languages: languages.map((lang, i) => {
+        const nav = navigations[i];
+        const children = Array.isArray(nav) ? { pages: nav } : nav;
+        return { language: lang, ...(LANGUAGE_NAMES[lang] ? { label: LANGUAGE_NAMES[lang] } : {}), ...children };
+      }),
+    };
+    notes.add('languages', ['languages'], `Each language (${languages.join(', ')}) got its own navigation. A page with a translation in translations/<language>/ uses it; the others show the ${languages[0]} page.`);
+  } else {
+    config.navigation = navigations[0];
+  }
+
+  if (missing.length) {
+    const message = `${missing.length === 1 ? 'A page' : `${missing.length} pages`} the sidebars list ${missing.length === 1 ? "isn't" : "aren't"} in docs/ - left out of the navigation: ${missing
+      .slice(0, 3)
+      .map((m) => `"${m.id}"`)
+      .join(', ')}${missing.length > 3 ? ', ...' : ''}.`;
+    const suggestion = "If they were generated from an OpenAPI spec that's a URL, download the spec first; otherwise add the pages, or fix their paths.";
+    for (const m of missing) notes.add('missing', m.trail, message, suggestion);
+  }
+  for (const [ref, { i }] of sidebars) {
+    if (!usedSidebars.has(ref)) notes.add('sidebar-unused', ['sidebars', i], 'Sidebars no navbar item points at were left out.');
+  }
+
+  // --- Homepage and redirects ----------------------------------------------
+  const redirectList = [];
+  if (nonEmpty(old.homepage)) {
+    const home = old.homepage.trim();
+    if (/\.html?$/i.test(home)) {
+      notes.add('homepage-html', ['homepage'], `The HTML homepage (${home}) isn't converted - "/" now opens the first page in the navigation.`, 'For a landing page, add index.mdx with `mode: custom` in its frontmatter, and rebuild the homepage there.');
+    } else {
+      const byUrl = redirects.get(`/${home.replace(/^\/+|\/+$/g, '')}`);
+      const byId = findPage(home);
+      const target = byUrl ?? (byId ? urlOf(byId.rel, byId.data.slug) : null) ?? [...pageUrls].find((u) => u === `/${home.replace(/^\/+|\/+$/g, '')}/`);
+      if (target && target !== '/') redirectList.push({ source: '/', destination: target });
+      else if (!target) notes.add('homepage', ['homepage'], `The homepage "${home}" isn't a page in the navigation - "/" opens the first page instead.`);
+    }
+  }
+  let unsafe = 0;
+  for (const [source, destination] of redirects) {
+    // A path a page is served at now can't also be a redirect.
+    if (pageUrls.has(`${source}/`) || source === '/') continue;
+    if (!/^[A-Za-z0-9\-._~/]+$/.test(source)) {
+      unsafe += 1;
+      continue;
+    }
+    redirectList.push({ source, destination });
+  }
+  if (redirectList.length) config.redirects = redirectList;
+  if (redirects.size) {
+    notes.add(
+      'redirects',
+      ['sidebars'],
+      `Pages are served at new addresses when they don't set \`slug\` in their frontmatter (writedocs puts the folder path in the address). ${redirectList.filter((r) => r.source !== '/').length} redirects from the old addresses were added.${unsafe ? ` ${unsafe} old addresses have spaces or other characters a redirect can't match - add a \`slug\` to those pages to keep their address.` : ''}`
+    );
+  }
+  if (apiPaths.size) notes.add('api-redirects', ['apiFiles'], 'API pages generated from a spec have new addresses; no redirects were added for them.');
+
+  // --- Links, integrations, the rest ---------------------------------------
+  if (Array.isArray(old.externalLinks) && old.externalLinks.length) {
+    const links = old.externalLinks.filter((l) => nonEmpty(l?.link)).map((l) => ({ label: String(l.name ?? l.link), href: l.link }));
+    if (links.length) config.topbar = { links };
+    if (old.externalLinks.some((l) => (l?.style ?? 'button') === 'button')) {
+      notes.add('button', ['externalLinks'], 'External links styled as buttons are plain topbar links in writedocs.');
+    }
+  }
+
+  const integrations = {};
+  const oldIntegrations = old.integrations ?? {};
+  if (nonEmpty(oldIntegrations.gtag)) {
+    const tag = oldIntegrations.gtag.trim();
+    if (/^GTM-/i.test(tag)) integrations.googleTagManager = { containerId: tag };
+    else if (/^G-/i.test(tag)) integrations.ga4 = { measurementId: tag };
+    else notes.add('gtag', ['integrations', 'gtag'], `gtag "${tag}" isn't a GA4 ("G-...") or Google Tag Manager ("GTM-...") id - dropped.`);
+  }
+  if (nonEmpty(oldIntegrations.posthog?.api_key)) {
+    integrations.posthog = { apiKey: oldIntegrations.posthog.api_key, ...(nonEmpty(oldIntegrations.posthog.api_host) ? { apiHost: oldIntegrations.posthog.api_host } : {}) };
+  }
+  if (oldIntegrations.askAi && Object.keys(oldIntegrations.askAi).length) {
+    notes.add('askAi', ['integrations', 'askAi'], `askAi connected a support tool (${Object.keys(oldIntegrations.askAi).join(', ')}) - writedocs' Ask AI is DocsBot, configured differently.`, 'Set integrations.askAi.id to your DocsBot "teamId/botId", or add the support tool\'s widget with `scripts`.');
+  }
+  if (Object.keys(integrations).length) config.integrations = integrations;
+
+  if (images.metadata && assetPath(images.metadata)) config.seo = { ogImage: assetPath(images.metadata) };
+
+  if (old.changelog === true) notes.add('changelog', ['changelog'], 'The changelog tab (changelog/ folder) isn\'t converted.', 'Write it as a page with an <Update> entry per release, and add it to the navigation.');
+  if (old.footer?.copyright) notes.add('footer', ['footer', 'copyright'], 'writedocs\' footer has no copyright line - dropped.', 'Footer links go in `footer.columns`.');
+  if (old.apiOptions?.hideSendButton) notes.add('hideSendButton', ['apiOptions', 'hideSendButton'], 'The API playground always has its "Send" button in writedocs.');
+  if (Array.isArray(old.codeLanguages) && old.codeLanguages.length) notes.add('codeLanguages', ['codeLanguages'], 'The API playground\'s code languages aren\'t configurable in writedocs - it shows its own set.');
+  if (old.translatedApiFiles && Object.values(old.translatedApiFiles).some((v) => Array.isArray(v) && v.length)) {
+    notes.add('translatedApiFiles', ['translatedApiFiles'], 'Translated OpenAPI specs aren\'t converted - every language uses the default spec.');
+  }
+  if (old.protected) notes.add('protected', ['protected'], 'Password-protected docs aren\'t supported - the converted site is public.');
+  for (const key of Object.keys(old)) {
+    if (!HANDLED_KEYS.has(key) && !PLATFORM_KEYS.has(key)) notes.add(`unknown-${key}`, [key], `\`${key}\` isn't a config.json field writedocs knows - dropped.`);
+  }
+  if (fs.existsSync(path.join(contentDir, 'custom.css'))) {
+    notes.add('css', ['custom.css'], 'custom.css is loaded on every page by writedocs too, but its Docusaurus class names don\'t exist here.', 'Review it - rules for Docusaurus classes (.navbar, .menu, .theme-doc-...) do nothing now.');
+  }
+
+  return { config, notes: notes.list() };
+}
+
+/** translations.json: { <lang>: { navbar: { label: text }, sidebars: {
+ *  <sidebarRef>: { name: text } } } } - the old generator's translated
+ *  navbar labels and category/group names. */
+function readTranslations(contentDir) {
+  try {
+    return JSON.parse(fs.readFileSync(path.join(contentDir, 'translations.json'), 'utf-8')) ?? {};
+  } catch {
+    return {};
+  }
+}