@writedocs/generator 0.7.1 → 0.7.3

package/src/cli/update.js

@@ -0,0 +1,112 @@
+// `writedocs update` - installs the latest writedocs, the same way the running
+// one was installed: globally with npm (the documented way), as a project
+// dependency (npm, pnpm or yarn, by the project's lockfile), or globally
+// with pnpm or yarn. npx and a source checkout get an explanation instead.
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { log, step, color, CliExit } from './output.js';
+import { fetchLatestVersion, isNewer, isSourceCheckout, writeCache } from './update-check.js';
+
+/** Runs a command, capturing its output. Resolves { code, output }. */
+function run(command, args, cwd) {
+  return new Promise((resolve) => {
+    // npm/pnpm/yarn are .cmd scripts on Windows, which spawn() only runs
+    // through a shell - given as one string there (Node deprecates an
+    // argument list with `shell`). The arguments are fixed: flags and the
+    // package name, never user input.
+    const options = { cwd, stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true };
+    const child = process.platform === 'win32' ? spawn([command, ...args].join(' '), { ...options, shell: true }) : spawn(command, args, options);
+    let output = '';
+    child.stdout.on('data', (d) => (output += d));
+    child.stderr.on('data', (d) => (output += d));
+    child.on('error', (err) => resolve({ code: 1, output: err.message }));
+    child.on('close', (code) => resolve({ code: code ?? 1, output }));
+  });
+}
+
+/** How the running writedocs was installed:
+ *  { kind: 'checkout' | 'npx' | 'unknown' } or
+ *  { kind: 'global' | 'local', command, args, cwd }. */
+export async function installation(packageRoot, name) {
+  if (isSourceCheckout(packageRoot)) return { kind: 'checkout' };
+  const posix = packageRoot.split(path.sep).join('/');
+  if (/\/_npx\//.test(posix)) return { kind: 'npx' };
+  if (/\/pnpm\/global\//.test(posix)) return { kind: 'global', command: 'pnpm', args: ['add', '-g', `${name}@latest`] };
+  if (/\/yarn\/global\//.test(posix)) return { kind: 'global', command: 'yarn', args: ['global', 'add', `${name}@latest`] };
+  // pnpm's default layout keeps the real package inside its store,
+  // <project>/node_modules/.pnpm/<name>@<version>/node_modules/<name>, and
+  // Node resolves the symlink to that path - so the project is what comes
+  // before .pnpm, not before the last node_modules/<name>.
+  const pnpmStore = posix.indexOf('/node_modules/.pnpm/');
+  const at = pnpmStore !== -1 ? pnpmStore : posix.lastIndexOf(`/node_modules/${name}`);
+  if (at === -1) return { kind: 'unknown' };
+  const container = posix.slice(0, at);
+  const npmRoot = await run('npm', ['root', '-g']);
+  const globalRoot = npmRoot.code === 0 ? npmRoot.output.trim().split(/\r?\n/).pop() : null;
+  if (globalRoot && path.resolve(globalRoot) === path.resolve(`${container}/node_modules`)) {
+    return { kind: 'global', command: 'npm', args: ['install', '-g', `${name}@latest`] };
+  }
+  const cwd = path.resolve(container);
+  if (fs.existsSync(path.join(cwd, 'pnpm-lock.yaml'))) return { kind: 'local', command: 'pnpm', args: ['add', `${name}@latest`], cwd };
+  if (fs.existsSync(path.join(cwd, 'yarn.lock'))) return { kind: 'local', command: 'yarn', args: ['add', `${name}@latest`], cwd };
+  return { kind: 'local', command: 'npm', args: ['install', `${name}@latest`], cwd };
+}
+
+export async function runUpdate({ name, version, packageRoot }) {
+  const checking = step('Checking for a new version');
+  let latest;
+  try {
+    latest = await fetchLatestVersion(name, { timeoutMs: 15000 });
+  } catch (err) {
+    checking.fail("Couldn't check for a new version");
+    log.detail(color.dim(`${err.message}. Check your connection, and try again.`));
+    throw new CliExit(1);
+  }
+  checking.stop();
+  try {
+    writeCache({ name, latest, checkedAt: Date.now() });
+  } catch {}
+  if (!isNewer(latest, version)) {
+    log.success(`writedocs is up to date ${color.dim(`(${version})`)}`);
+    return;
+  }
+
+  const install = await installation(packageRoot, name);
+  if (install.kind === 'checkout') {
+    log.info(`writedocs ${latest} is available, but this one runs from a source checkout (${packageRoot}).`);
+    log.detail(color.dim('Update it with git - `writedocs update` only updates installed copies.'));
+    return;
+  }
+  if (install.kind === 'npx') {
+    log.info(`writedocs ${latest} is available. You're running writedocs through npx - to use the latest, run:`);
+    log.detail(color.cyan(`npx ${name}@latest <command>`));
+    log.detail(color.dim(`Or install it once, and use \`writedocs\` directly: npm install -g ${name}`));
+    return;
+  }
+  if (install.kind === 'unknown') {
+    log.info(`writedocs ${latest} is available. Update it the way you installed it - for example:`);
+    log.detail(color.cyan(`npm install -g ${name}@latest`));
+    return;
+  }
+
+  const shown = `${install.command} ${install.args.join(' ')}`;
+  const updating = step(`Updating writedocs ${version} → ${latest} ${color.dim(`(${shown}${install.cwd ? ` in ${install.cwd}` : ''})`)}`);
+  const result = await run(install.command, install.args, install.cwd);
+  if (result.code !== 0) {
+    updating.fail(`Couldn't update writedocs - \`${shown}\` failed`);
+    const tail = result.output.trim().split(/\r?\n/).slice(-12).join('\n');
+    if (tail) {
+      log.line();
+      log.line(color.dim(tail));
+    }
+    if (/EACCES|permission denied/i.test(result.output)) {
+      log.line();
+      log.detail(
+        `npm needs permission to write to its global folder. Run ${color.cyan(`sudo ${shown}`)}, or set npm up to install without sudo: https://docs.npmjs.com/resolving-eacces-permissions-errors-when-installing-packages-globally`
+      );
+    }
+    throw new CliExit(1);
+  }
+  updating.succeed(`Updated writedocs ${version} → ${color.bold(latest)}`);
+}

package/src/cli/write-redirects-file.js

@@ -1,5 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { readConfigText } from '../lib/config-file.js';
 
 // Astro's own `output: 'static'` redirects (both writedocs.json's `redirects`
 // feature and the automatic "/" -> first-nav-page redirect in
@@ -31,7 +32,7 @@ import path from 'node:path';
 // the one `redirects` array back out, nothing that needs zod's defaults
 // or transforms.
 export function writeRedirectsFile(distDir, contentDir) {
-  const writedocsJson = JSON.parse(fs.readFileSync(path.join(contentDir, 'writedocs.json'), 'utf8'));
+  const writedocsJson = JSON.parse(readConfigText(contentDir));
   const redirects = writedocsJson.redirects ?? [];
   const lines = [];
 

package/src/components/ApiReferencePanel.astro

@@ -658,7 +658,7 @@ const securityJson = JSON.stringify(op?.security ?? []);
     border-radius: 0.5rem;
     border: none;
     background: var(--wd-primary);
-    color: #fff;
+    color: var(--wd-on-primary);
     font-size: 0.75rem;
     font-weight: 600;
     cursor: pointer;
@@ -931,7 +931,7 @@ const securityJson = JSON.stringify(op?.security ?? []);
     border-radius: 0.4rem;
     border: none;
     background: var(--wd-primary);
-    color: #fff;
+    color: var(--wd-on-primary);
     font-size: 0.85rem;
     font-weight: 600;
     cursor: pointer;
@@ -1123,6 +1123,8 @@ const securityJson = JSON.stringify(op?.security ?? []);
   // after the base (protocol required), preserving method/headers/body,
   // and returns CORS headers so the browser fetch() below succeeds even
   // when the target API itself doesn't send Access-Control-Allow-Origin.
+  // Only a fallback: a request goes straight to the API first, and through
+  // here only when the browser blocks that (see the send handler below).
   // Toggle via writedocs.json's `api.proxy` (see data-proxy on the tryit
   // section below); the displayed curl/fetch/python snippets deliberately
   // keep showing the real, non-proxied URL - only this in-browser request
@@ -1322,17 +1324,26 @@ const securityJson = JSON.stringify(op?.security ?? []);
       const responseBodyEl = section.querySelector<HTMLElement>('[data-role="response-body"] code');
       const modalLangPanels = Array.from(section.querySelectorAll<HTMLElement>('[data-modal-lang-panel]'));
 
+      // A reader's credentials last for the tab, not forever: sessionStorage
+      // carries them across the pages of one visit and forgets them when the
+      // tab closes. Older versions kept them in localStorage indefinitely -
+      // a key found there is moved over once and deleted.
       authInputs.forEach((input) => {
-        const name = input.dataset.authName ?? '';
+        const storageKey = `wd-api-auth:${input.dataset.authName ?? ''}`;
         try {
-          const saved = localStorage.getItem(`wd-api-auth:${name}`);
+          const legacy = localStorage.getItem(storageKey);
+          if (legacy !== null) {
+            if (sessionStorage.getItem(storageKey) === null) sessionStorage.setItem(storageKey, legacy);
+            localStorage.removeItem(storageKey);
+          }
+          const saved = sessionStorage.getItem(storageKey);
           if (saved) input.value = saved;
         } catch {
-          // localStorage unavailable - auth just won't persist across reloads
+          // storage unavailable - auth just won't carry across pages
         }
         input.addEventListener('input', () => {
           try {
-            localStorage.setItem(`wd-api-auth:${name}`, input.value);
+            sessionStorage.setItem(storageKey, input.value);
           } catch {
             // ignore
           }
@@ -1714,9 +1725,13 @@ const securityJson = JSON.stringify(op?.security ?? []);
         }
 
         const targetUrl = baseUrl + requestPath + (query.toString() ? `?${query.toString()}` : '');
-        // Route through writedocs' CORS proxy unless disabled via writedocs.json's
-        // `api.proxy: false` - see PROXY_BASE_URL above for the contract.
-        const url = proxyEnabled ? `${PROXY_BASE_URL}${targetUrl}` : targetUrl;
+        // A "simple" request (CORS spec: GET/HEAD/POST, no JSON body, no
+        // auth or custom headers) skips the preflight, so the server may
+        // already have run it when the browser blocks the response.
+        // Retrying one that changes something (a POST) through the proxy
+        // could run it twice - so that one case isn't retried.
+        const isSimple = ['GET', 'HEAD', 'POST'].includes(method) && Object.keys(headers).length === 0;
+        const mayHaveRun = isSimple && method === 'POST';
 
         if (sendBtn) {
           sendBtn.disabled = true;
@@ -1727,8 +1742,23 @@ const securityJson = JSON.stringify(op?.security ?? []);
         responseBodyEl.textContent = '';
 
         const startedAt = performance.now();
+        let viaProxy = false;
         try {
-          const res = await fetch(url, { method, headers, body });
+          // Straight to the API first, so a reader's key and body only reach
+          // the API itself. fetch() rejects when the browser blocks the
+          // response (CORS) or can't reach the host - only then, and only
+          // when writedocs.json's `api.proxy` allows it, the same request is
+          // retried through writedocs' proxy (PROXY_BASE_URL above), and the
+          // status line says so.
+          let res: Response;
+          try {
+            res = await fetch(targetUrl, { method, headers, body });
+          } catch (directErr) {
+            if (!proxyEnabled || mayHaveRun) throw directErr;
+            viaProxy = true;
+            responseStatusEl.textContent = 'Blocked by the browser (CORS) - retrying through the writedocs proxy...';
+            res = await fetch(`${PROXY_BASE_URL}${targetUrl}`, { method, headers, body });
+          }
           const elapsed = Math.round(performance.now() - startedAt);
           const text = await res.text();
           let pretty = text;
@@ -1737,11 +1767,15 @@ const securityJson = JSON.stringify(op?.security ?? []);
           } catch {
             // not JSON - show raw text as-is
           }
-          responseStatusEl.textContent = `${res.status} ${res.statusText} - ${elapsed}ms`;
+          responseStatusEl.textContent = `${res.status} ${res.statusText} - ${elapsed}ms${viaProxy ? ' - sent through the writedocs proxy (the API blocks direct browser requests)' : ''}`;
           responseStatusEl.className = `wd-api-response-status ${res.ok ? 'wd-api-status-ok' : 'wd-api-status-error'}`;
           responseBodyEl.textContent = pretty;
         } catch (err) {
-          responseStatusEl.textContent = 'Request failed - likely blocked by CORS, or the base URL is unreachable from your browser.';
+          responseStatusEl.textContent = viaProxy
+            ? 'Request failed through the writedocs proxy too - the base URL may be unreachable from the internet.'
+            : mayHaveRun && proxyEnabled
+              ? 'Blocked by the browser (CORS). Not retried through the proxy: this POST may already have reached the API.'
+              : 'Request failed - likely blocked by CORS, or the base URL is unreachable from your browser.';
           responseStatusEl.className = 'wd-api-response-status wd-api-status-error';
           responseBodyEl.textContent = err instanceof Error ? err.message : String(err);
         } finally {

package/src/components/Steps.astro

@@ -27,7 +27,7 @@ import { extraClasses } from './class-names';
     height: 1.8rem;
     padding: 0.45rem;
     box-sizing: border-box;
-    color: white;
+    color: var(--wd-on-primary);
     z-index: 1;
   }
   span.wd-step-icon {
@@ -47,7 +47,7 @@ import { extraClasses } from './class-names';
     height: 1.8rem;
     border-radius: 50%;
     background: var(--wd-primary);
-    color: white;
+    color: var(--wd-on-primary);
     font-size: 0.85rem;
     font-weight: 600;
     display: flex;

package/src/layout/BaseLayout.astro

@@ -116,6 +116,9 @@ interface Props {
   // renders nothing, so this component only needs to know whether to
   // render the *column wrapper divs* at all).
   mode?: 'default' | 'wide' | 'frame' | 'custom' | 'blank';
+  // The page's language, for <html lang> - the `language` of the
+  // navigation level it belongs to (see [...slug].astro), or 'en'.
+  lang?: string;
 }
 const {
   config,
@@ -126,6 +129,7 @@ const {
   selectors = [],
   globalDropdowns = [],
   mode = 'default',
+  lang = 'en',
 } = Astro.props as Props;
 const showSidebarCol = mode === 'default' || mode === 'wide';
 const showTocCol = mode === 'default';
@@ -158,6 +162,13 @@ const lightPrimary = config.styles.colors.primary;
 const lightText = config.styles.colors.text ?? '#0f172a';
 const darkPrimary = config.styles.colors.dark?.primary ?? lightPrimary;
 const darkText = config.styles.colors.dark?.text ?? '#e2e8f0';
+// Text drawn on the primary color (step numbers, the info banner, the API
+// playground's buttons) - white, or black on a clearly light primary
+// (contrastTextColor(), lib/config.ts). It used to be white everywhere,
+// unreadable on a light primary - and a light dark-mode primary is exactly
+// what dark-mode links need.
+const lightOnPrimary = contrastTextColor(lightPrimary);
+const darkOnPrimary = contrastTextColor(darkPrimary);
 // styles.background.colors is now the single source for any background
 // color - both the flat --wd-background surface (dropdowns/modals/kbd
 // chips/footer/topbar-fallback/etc., every other `var(--wd-background)`
@@ -309,7 +320,7 @@ const footerLogoDark = footerLogoConfig
 // Zero-config custom CSS/JS - any `.css`/`.js` file anywhere in the
 // project (root, `docs/`, `snippets/`, `public/`, any subfolder -
 // `dist/`/`node_modules/`/etc. excluded, see findRootAssets() in
-// lib/config.ts) is auto-loaded on every page, no writedocs.json entry
+// lib/pages.js) is auto-loaded on every page, no writedocs.json entry
 // needed. Read fresh on every render (not cached at module scope) so an
 // edit to one of these files shows up on the next `writedocs dev` page
 // load without a server restart - same freshness `loadDocsConfig(contentDir)`
@@ -400,7 +411,7 @@ const fontWeightCss = [
 const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
 ---
 <!doctype html>
-<html lang="en">
+<html lang={lang}>
   <head>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
@@ -509,6 +520,7 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
     <style
       define:vars={{
         wdPrimaryLight: lightPrimary,
+        wdOnPrimaryLight: lightOnPrimary,
         wdBackgroundLight: lightBackground,
         wdTextLight: lightText,
         wdNavbarLight: lightNavbarBg,
@@ -523,6 +535,7 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
         wdFontFamilyHeading,
         wdFontFamilyBody,
         wdPrimaryDark: darkPrimary,
+        wdOnPrimaryDark: darkOnPrimary,
         wdBackgroundDark: darkBackground,
         wdTextDark: darkText,
         wdNavbarDark: darkNavbarBg,
@@ -537,6 +550,7 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
     >
       :root {
         --wd-primary: var(--wdPrimaryLight);
+        --wd-on-primary: var(--wdOnPrimaryLight);
         --wd-background: var(--wdBackgroundLight);
         --wd-text: var(--wdTextLight);
         --wd-navbar-background: var(--wdNavbarLight);
@@ -564,6 +578,7 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
          (src/scripts/theme-toggle.ts). */
       :root[data-theme='dark'] {
         --wd-primary: var(--wdPrimaryDark);
+        --wd-on-primary: var(--wdOnPrimaryDark);
         --wd-background: var(--wdBackgroundDark);
         --wd-text: var(--wdTextDark);
         --wd-navbar-background: var(--wdNavbarDark);
@@ -603,7 +618,7 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
     {config.scripts.head.map((s) =>
       s.src ? <script is:inline src={s.src} /> : <script is:inline set:html={s.content} />
     )}
-    {/* Zero-config custom CSS - see findRootAssets() in lib/config.ts and
+    {/* Zero-config custom CSS - see findRootAssets() in lib/pages.js and
         rootCssContents above. Rendered last in <head>, so a project-owned
         file - anywhere in the project, not just the root - wins over
         everything else writedocs generates itself. Inlined as raw <style>
@@ -617,7 +632,7 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
       <style is:inline set:html={content} />
     ))}
     {/* Zero-config custom CSS living in public/ - see findRootAssets()'s
-        own comment in lib/config.ts for why these render as <link> tags
+        own comment in lib/pages.js for why these render as <link> tags
         pointing at their already-public URL instead of joining
         rootCssContents above as inlined content. */}
     {publicCssHrefs.map((href) => (
@@ -712,7 +727,7 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
     {config.scripts.body.map((s) =>
       s.src ? <script is:inline src={s.src} /> : <script is:inline set:html={s.content} />
     )}
-    {/* Zero-config custom JS - see findRootAssets() in lib/config.ts and
+    {/* Zero-config custom JS - see findRootAssets() in lib/pages.js and
         rootJsContents above. Rendered last, after writedocs.json's own
         `scripts.body`, same "most locally-owned override runs last"
         reasoning as the root CSS above. `is:inline` here isn't optional -
@@ -725,7 +740,7 @@ const fontExtraCss = [fontFaceCss, fontWeightCss].filter(Boolean).join('\n');
       <script is:inline set:html={content} />
     ))}
     {/* Zero-config custom JS living in public/ - see this file's own CSS
-        equivalent above and findRootAssets()'s comment in lib/config.ts.
+        equivalent above and findRootAssets()'s comment in lib/pages.js.
         `<script src>`, not `is:inline set:html` - the file's already a
         fetchable URL, no reason to inline its content. Filtered against
         config.scripts.head's own `src` entries (publicJsHrefs) for the

package/src/layout/styles/banner.css

@@ -15,7 +15,7 @@
 .wd-banner {
   width: 100%;
 }
-.wd-banner-info { background: var(--wd-primary); color: #fff; }
+.wd-banner-info { background: var(--wd-primary); color: var(--wd-on-primary); }
 .wd-banner-warning { background: #b45309; color: #fff; }
 .wd-banner-critical { background: #b91c1c; color: #fff; }
 .wd-banner-inner {

package/src/lib/a11y-check.js

@@ -5,8 +5,8 @@
 //
 //   - contrast (WCAG 2 AA, 4.5:1 for text) of the colors writedocs.json sets:
 //     links (styles.colors.primary) on the light and dark backgrounds, body
-//     text (styles.colors.text) on them, white text on primary (step
-//     numbers, the info banner), and the navbar's text on its own color.
+//     text (styles.colors.text) on them, text on primary (step numbers, the
+//     info banner), and the navbar's text on its own color.
 //     Only colors the project sets are checked - writedocs' own defaults
 //     aren't something the author wrote.
 //   - images without alt text: a Markdown image with empty alt, an
@@ -27,6 +27,7 @@ import matter from 'gray-matter';
 import { visit } from 'unist-util-visit';
 import { findAllPages } from './pages.js';
 import { createJsonLocator } from './config-schema.js';
+import { contrastRatio, readableTextOn } from './color.js';
 
 const processors = {};
 async function parse(text, format) {
@@ -44,38 +45,9 @@ const DEFAULT_BACKGROUND = { light: '#ffffff', dark: '#0b1120' };
 const DEFAULT_TEXT = { light: '#0f172a', dark: '#e2e8f0' };
 const MIN_TEXT_CONTRAST = 4.5;
 
-function parseHex(value) {
-  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(String(value ?? '').trim());
-  if (!m) return null;
-  const hex = m[1].length === 3 ? [...m[1]].map((c) => c + c).join('') : m[1];
-  return [0, 2, 4].map((i) => parseInt(hex.slice(i, i + 2), 16));
-}
-
-function luminance(rgb) {
-  const [r, g, b] = rgb.map((v) => {
-    const c = v / 255;
-    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
-  });
-  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
-}
-
-/** WCAG contrast ratio of two hex colors, or null when either isn't hex. */
-export function contrastRatio(a, b) {
-  const x = parseHex(a);
-  const y = parseHex(b);
-  if (!x || !y) return null;
-  const [hi, lo] = [luminance(x), luminance(y)].sort((p, q) => q - p);
-  return (hi + 0.05) / (lo + 0.05);
-}
-
-/** Black or white - the same rule BaseLayout.astro uses for text on a
- *  configured navbar color (contrastTextColor() in lib/config.ts). */
-function navbarTextFor(hex) {
-  const rgb = parseHex(hex);
-  if (!rgb) return '#ffffff';
-  const [r, g, b] = rgb;
-  return (299 * r + 587 * g + 114 * b) / 1000 > 150 ? '#000000' : '#ffffff';
-}
+// contrastRatio() is re-exported: it was defined here, and tests import it
+// from this module.
+export { contrastRatio };
 
 function checkColors(config, locate) {
   const issues = [];
@@ -127,32 +99,37 @@ function checkColors(config, locate) {
     }
   }
 
-  // White text on the primary color (step numbers, the info banner).
+  // Text drawn on the primary color (step numbers, the info banner, the API
+  // playground's buttons) - the color the theme picks (readableTextOn() in
+  // lib/color.js): white, unless white falls below 3:1 and black takes over.
+  // So white between 3:1 and 4.5:1 - most mid-tone brand colors - is the
+  // one case left to report.
   const primaries = [...new Set([colors.primary, colors.dark?.primary].filter(Boolean))];
   for (const color of primaries) {
-    const r = low('#ffffff', color);
+    const fg = readableTextOn(color);
+    const r = low(fg, color);
     if (r) {
       push(
         color === colors.primary ? at('colors', 'primary') : at('colors', 'dark', 'primary'),
-        `White text on the primary color ${color} (step numbers, the info banner) has a contrast of ${ratioText(r)} (needs ${MIN_TEXT_CONTRAST}:1).`,
-        'Use a darker primary color.'
+        `${fg === '#ffffff' ? 'White' : 'Black'} text on the primary color ${color} (step numbers, the info banner) has a contrast of ${ratioText(r)} (needs ${MIN_TEXT_CONTRAST}:1).`,
+        'Use a darker primary color - or a much lighter one, which gets black text.'
       );
     }
   }
 
-  // The navbar's text on its own color - black or white, picked by a rough
-  // brightness rule that can land on the weaker of the two.
+  // The navbar's text on its own color - the same rule (contrastTextColor()
+  // in lib/config.ts), with the same gap for mid-tones.
   for (const mode of ['light', 'dark']) {
     const side = styles.navbar?.[mode];
     const bg = typeof side === 'string' ? side : side?.background;
     if (!bg) continue;
-    const fg = navbarTextFor(bg);
+    const fg = readableTextOn(bg);
     const r = low(fg, bg);
     if (r) {
       push(
         at('navbar', mode, ...(typeof side === 'string' ? [] : ['background'])),
         `The navbar's ${fg === '#ffffff' ? 'white' : 'black'} text on ${bg} (${mode} mode) has a contrast of ${ratioText(r)} (needs ${MIN_TEXT_CONTRAST}:1).`,
-        'Use a darker or a lighter navbar color - mid-tones can\'t reach 4.5:1 with either black or white text.'
+        'Use a darker navbar color - or a much lighter one, which gets black text.'
       );
     }
   }

package/src/lib/asset-path.js

@@ -0,0 +1,29 @@
+// Where a root-relative asset URL points inside a project - for
+// styles-asset-integration.js's dev-server middleware and build copy. Plain
+// JavaScript with no config.ts import, so it can be tested with plain Node.
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** Resolves a root-relative `urlPath` (e.g. "/images/hero.svg") against
+ *  `contentDir` directly - not `<contentDir>/public` - the fallback
+ *  location for one of the styles/footer/seo asset fields
+ *  (collectConfiguredAssetPaths()) when it isn't sitting under public/.
+ *  `urlPath` comes from an incoming request URL in the dev-server case, not
+ *  just trusted writedocs.json content, so it must never resolve outside
+ *  the project: no `..`/`.` segments, and the resolved path itself has to
+ *  stay inside contentDir - on Windows `\` is a separator too, and a raw
+ *  request for `/x\..\..\secret.png` has no `..` segment yet walked out of
+ *  the project. Returns an absolute path, or null if nothing real is there. */
+export function resolveOutsidePublic(urlPath, contentDir) {
+  const segments = urlPath.replace(/^\/+/, '').split('/');
+  if (segments.some((segment) => segment === '..' || segment === '.' || segment === '')) return null;
+  const root = path.resolve(contentDir);
+  const absolute = path.resolve(root, ...segments);
+  const inside = path.relative(root, absolute);
+  if (!inside || inside.startsWith('..') || path.isAbsolute(inside)) return null;
+  try {
+    return fs.statSync(absolute).isFile() ? absolute : null;
+  } catch {
+    return null;
+  }
+}

package/src/lib/color.js

@@ -0,0 +1,49 @@
+// WCAG 2 color math - shared by the theme (BaseLayout.astro, through
+// contrastTextColor() in lib/config.ts), which picks the text color that
+// goes on a configured color, and by `writedocs a11y` (lib/a11y-check.js),
+// which checks that choice. One implementation, so the check always
+// measures what the site actually renders. Plain JavaScript, loaded by
+// plain Node from an installed package (see lib/icons.js's comment).
+
+/** [r, g, b] for `#rgb`/`#rrggbb` (the `#` optional), or null. */
+export function parseHex(value) {
+  const m = /^#?([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(String(value ?? '').trim());
+  if (!m) return null;
+  const hex = m[1].length === 3 ? [...m[1]].map((c) => c + c).join('') : m[1];
+  return [0, 2, 4].map((i) => parseInt(hex.slice(i, i + 2), 16));
+}
+
+/** WCAG relative luminance of an [r, g, b] triple. */
+export function luminance(rgb) {
+  const [r, g, b] = rgb.map((v) => {
+    const c = v / 255;
+    return c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/** WCAG contrast ratio of two hex colors, or null when either isn't hex. */
+export function contrastRatio(a, b) {
+  const x = parseHex(a);
+  const y = parseHex(b);
+  if (!x || !y) return null;
+  const [hi, lo] = [luminance(x), luminance(y)].sort((p, q) => q - p);
+  return (hi + 0.05) / (lo + 0.05);
+}
+
+/** Below this contrast, white text on a color switches to black. */
+export const WHITE_TEXT_MIN_CONTRAST = 3;
+
+/** The text color the theme puts on `hex`: white, as brand colors are
+ *  designed for, unless white falls below 3:1 - a clearly light color
+ *  (amber, sky, a light dark-mode primary), which gets black instead, at
+ *  7:1 or more. Pure "whichever has more contrast" turned most mid-tone
+ *  brand colors (blue-500, indigo-500, Mintlify's green) black; with this,
+ *  white between 3:1 and 4.5:1 is kept and `writedocs a11y` reports it
+ *  (lib/a11y-check.js). White too when `hex` isn't a hex color (a CSS
+ *  variable, a named color). */
+export function readableTextOn(hex) {
+  const white = contrastRatio('#ffffff', hex);
+  if (white === null) return '#ffffff';
+  return white < WHITE_TEXT_MIN_CONTRAST ? '#000000' : '#ffffff';
+}

package/src/lib/config-file.js

@@ -0,0 +1,25 @@
+// Reading writedocs.json (and the other JSON configs `writedocs convert`
+// reads) as text. Plain JavaScript, not TypeScript, so the CLI can load it
+// with plain Node - see lib/icons.js's comment.
+//
+// Windows editors - Notepad, PowerShell 5.1's `Out-File`/`Set-Content
+// -Encoding utf8` - save UTF-8 with a byte order mark. JSON.parse rejects
+// it ("Unexpected token ''"), and the error then blames commas and
+// brackets the file doesn't have. Every reader strips it here instead.
+import fs from 'node:fs';
+import path from 'node:path';
+
+/** `text` without a leading UTF-8 byte order mark. */
+export function stripBom(text) {
+  return text.charCodeAt(0) === 0xfeff ? text.slice(1) : text;
+}
+
+/** A JSON config file's text, byte order mark removed. */
+export function readJsonText(file) {
+  return stripBom(fs.readFileSync(file, 'utf-8'));
+}
+
+/** `<contentDir>/writedocs.json`'s text, byte order mark removed. */
+export function readConfigText(contentDir) {
+  return readJsonText(path.join(contentDir, 'writedocs.json'));
+}