@writedocs/generator 0.5.0 → 0.7.0

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

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

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/openapi-spec.js

@@ -0,0 +1,73 @@
+// OpenAPI specs as writedocs uses them - which ones writedocs.json's
+// navigation points at, and which operations a spec defines. Shared by
+// generate-api-pages.js (which turns them into pages before every dev/build)
+// and lib/content-check.js (`writedocs validate`), so both find the same
+// specs and the same operations. Plain JavaScript: both run under plain Node.
+
+export const HTTP_METHODS = ['get', 'put', 'post', 'delete', 'options', 'head', 'patch', 'trace'];
+
+/** "METHOD /path" for every operation in a (dereferenced) spec - the key a
+ *  page's `openapi:` frontmatter names an operation by (see
+ *  openApiOperationKey() in lib/openapi-ref.js). */
+export function operationKeys(spec) {
+  const keys = new Set();
+  for (const [urlPath, pathItem] of Object.entries(spec?.paths ?? {})) {
+    for (const method of HTTP_METHODS) if (pathItem?.[method]) keys.add(`${method.toUpperCase()} ${urlPath}`);
+  }
+  return keys;
+}
+
+/** Walks writedocs.json's raw `navigation` tree (any shape - a bare array, or
+ *  an object choosing tabs/versions/languages/dropdowns/products, plus
+ *  `global.dropdowns`) looking for group nodes shaped like
+ *  `{ group, openapi: { src, path } }`, however deeply nested inside
+ *  hand-authored groups or containers. Runs directly against the raw
+ *  JSON (before writedocs.json's own zod validation even happens - this CLI
+ *  step runs first, see generateApiPages() below), so it deliberately
+ *  doesn't import anything from lib/config.ts and just duck-types each
+ *  node the same way lib/config.ts's own walkSections()/
+ *  expandOpenApiInContainer() do. */
+export function collectOpenApiGroups(navigation) {
+  const found = [];
+
+  function fromPagesItem(item) {
+    if (!item || typeof item !== 'object') return; // plain page-slug string - not a group
+    if (item.group && item.openapi) {
+      found.push(item);
+      return;
+    }
+    if (Array.isArray(item.pages)) {
+      for (const child of item.pages) fromPagesItem(child);
+    }
+    // otherwise a { label, href } link leaf - nothing to collect
+  }
+
+  function fromContainer(node) {
+    if (!node || typeof node !== 'object') return;
+    if (Array.isArray(node.pages)) {
+      for (const item of node.pages) fromPagesItem(item);
+    } else if (Array.isArray(node.tabs)) {
+      for (const t of node.tabs) fromContainer(t);
+    } else if (Array.isArray(node.versions)) {
+      for (const v of node.versions) fromContainer(v);
+    } else if (Array.isArray(node.languages)) {
+      for (const l of node.languages) fromContainer(l);
+    } else if (Array.isArray(node.dropdowns)) {
+      for (const d of node.dropdowns) fromContainer(d);
+    } else if (Array.isArray(node.products)) {
+      for (const p of node.products) fromContainer(p);
+    }
+    // otherwise a bare { href } container - nothing to collect
+  }
+
+  if (Array.isArray(navigation)) {
+    for (const item of navigation) fromPagesItem(item);
+  } else if (navigation && typeof navigation === 'object') {
+    if (Array.isArray(navigation.global?.dropdowns)) {
+      for (const d of navigation.global.dropdowns) fromContainer(d);
+    }
+    fromContainer(navigation);
+  }
+
+  return found;
+}