@writedocs/generator 0.7.2 → 0.7.4

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/agent-markdown.js

@@ -0,0 +1,137 @@
+// The Markdown an AI agent reads for a page - llms-full.txt and the per-page
+// .md route. It starts from the page's raw MDX, so everything the build does
+// to that source on the way to HTML has to be redone here, or the agent reads
+// something other than the page: `<Visibility>` blocks, imported .mdx
+// snippets (inlined, as the page shows them) and writedocs.json `variables`.
+//
+// Code is left exactly as written - fenced blocks and inline `code` - the same
+// way the build never substitutes inside code: a page documenting the
+// `[[key]]` syntax, or showing `<Snippet />` in an example, must keep it.
+// Plain JavaScript, so it can be tested with plain Node.
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+import { applyVisibilityForAgents } from './visibility.js';
+
+/** `text` with `transform` applied to everything outside fenced code blocks
+ *  and inline code spans; code comes back untouched. */
+export function mapOutsideCode(text, transform) {
+  const out = [];
+  let prose = [];
+  let fence = null; // the opening marker (``` or ~~~, maybe longer) while inside a block
+  const flush = () => {
+    if (prose.length) out.push(mapOutsideInlineCode(prose.join('\n'), transform));
+    prose = [];
+  };
+  for (const line of text.split('\n')) {
+    const marker = /^\s*(`{3,}|~{3,})/.exec(line)?.[1];
+    if (fence) {
+      out.push(line);
+      if (marker && marker[0] === fence[0] && marker.length >= fence.length && line.trim() === marker) fence = null;
+    } else if (marker) {
+      flush();
+      fence = marker;
+      out.push(line);
+    } else {
+      prose.push(line);
+    }
+  }
+  flush();
+  return out.join('\n');
+}
+
+function mapOutsideInlineCode(text, transform) {
+  // Backtick runs of equal length delimit a code span (CommonMark).
+  return text
+    .split(/(`+)([\s\S]*?)(\1)(?!`)/)
+    .reduce((acc, part, i, parts) => {
+      const k = i % 4;
+      if (k === 0) acc.push(transform(part));
+      else if (k === 1) acc.push(part + parts[i + 1] + parts[i + 2]);
+      return acc;
+    }, [])
+    .join('');
+}
+
+const PLACEHOLDER = /\[\[\s*([\w.-]+)\s*\]\]/g;
+// A standalone `{key}` expression - not an attribute value (`prop={key}`),
+// which the build leaves alone too.
+const MINTLIFY_PLACEHOLDER = /(?<!=\s*)\{\s*([A-Za-z_$][\w$]*)\s*\}/g;
+
+/** writedocs.json `variables` - `[[key]]`, and Mintlify's `{key}` - replaced
+ *  the way the build replaces them (lib/mdx-substitute-variables.js): outside
+ *  code, and only for keys that exist. */
+export function substituteVariables(text, variables) {
+  if (!variables || Object.keys(variables).length === 0) return text;
+  const has = (key) => Object.prototype.hasOwnProperty.call(variables, key);
+  return mapOutsideCode(text, (prose) =>
+    prose
+      .replace(PLACEHOLDER, (match, key) => (has(key) ? String(variables[key]) : match))
+      .replace(MINTLIFY_PLACEHOLDER, (match, key) => (has(key) ? String(variables[key]) : match))
+  );
+}
+
+const IMPORT_LINE = /^[ \t]*import\s+([A-Za-z_$][\w$]*)\s+from\s+['"]([^'"]+\.mdx?)['"];?[ \t]*$/gm;
+
+function resolveSnippet(spec, fromFile, contentDir) {
+  if (spec.startsWith('/snippets/')) return path.join(contentDir, 'snippets', spec.slice('/snippets/'.length));
+  if (spec.startsWith('./') || spec.startsWith('../')) return path.resolve(path.dirname(fromFile), spec);
+  if (spec.startsWith('/')) return path.join(contentDir, spec.slice(1));
+  return null;
+}
+
+function attributesOf(source) {
+  const props = {};
+  for (const m of source.matchAll(/([A-Za-z_$][\w$-]*)\s*=\s*(?:"([^"]*)"|'([^']*)'|\{\s*["']([^"']*)["']\s*\})/g)) {
+    props[m[1]] = m[2] ?? m[3] ?? m[4];
+  }
+  return props;
+}
+
+function fillProps(snippet, props, children) {
+  return snippet
+    .replace(/\{\s*props\.children\s*\}/g, children ?? '')
+    .replace(/\{\s*props\.([A-Za-z_$][\w$]*)\s*\}/g, (match, key) => (key in props ? props[key] : match));
+}
+
+/** Imported .mdx snippets inlined where the page uses them - the snippet's
+ *  own text, with `{props.x}` filled from the tag's string attributes, and
+ *  its own imports inlined in turn. The import line goes too. A snippet that
+ *  can't be read, or a .jsx/.tsx component, stays as written. */
+export function inlineSnippets(text, { file, contentDir, depth = 0 }) {
+  if (depth > 5) return text;
+  const snippets = new Map();
+  let result = mapOutsideCode(text, (prose) =>
+    prose.replace(IMPORT_LINE, (line, name, spec) => {
+      const target = resolveSnippet(spec, file, contentDir);
+      let raw;
+      try {
+        raw = target && fs.readFileSync(target, 'utf-8');
+      } catch {
+        raw = null;
+      }
+      if (!raw) return line;
+      const body = inlineSnippets(matter(raw).content.trim(), { file: target, contentDir, depth: depth + 1 });
+      snippets.set(name, body);
+      return '';
+    })
+  );
+  for (const [name, body] of snippets) {
+    result = mapOutsideCode(result, (prose) =>
+      prose
+        .replace(new RegExp(`<${name}\\b([^>]*?)\\/>`, 'g'), (_, attrs) => fillProps(body, attributesOf(attrs)))
+        .replace(new RegExp(`<${name}\\b([^>]*)>([\\s\\S]*?)<\\/${name}>`, 'g'), (_, attrs, children) =>
+          fillProps(body, attributesOf(attrs), children.trim())
+        )
+    );
+  }
+  return result.replace(/\n{3,}/g, '\n\n');
+}
+
+/** A page's body as an agent should read it. `file` is the page's absolute
+ *  path (to resolve relative snippet imports). */
+export function markdownForAgents(body, { file, contentDir, variables }) {
+  let text = applyVisibilityForAgents(body ?? '');
+  if (file) text = inlineSnippets(text, { file, contentDir });
+  return substituteVariables(text, variables);
+}

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 U+FEFF"), 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'));
+}

package/src/lib/config-schema.js

@@ -379,18 +379,15 @@ const pageFrontmatterSchema = z.object({
   }
 );
 const apiSchema = z.object({
-  // Whether the Try-it modal's Send button routes its request through
-  // writedocs' own CORS proxy (https://proxy.writechoice.io/) rather
-  // than calling the API directly from the browser. Almost no
-  // real-world API sends back Access-Control-Allow-Origin headers
-  // permitting an arbitrary docs site's origin, so a direct browser
-  // fetch() from the Try-it modal fails for most real APIs without
-  // this - see PROXY_BASE_URL in ApiReferencePanel.astro for the
-  // actual request-forwarding logic. Defaults to enabled; a site can
-  // set this to `false` to always call the API directly instead (the
-  // API is already CORS-permissive, same-origin in some deployments,
-  // or the site owner doesn't want requests routed through a third
-  // party at all).
+  // Whether a Try-it request the browser blocks is retried through
+  // writedocs' own CORS proxy (https://proxy.writechoice.io/). The
+  // request always goes to the API directly first, so a reader's key
+  // reaches the proxy only when the API itself refuses browser calls.
+  // Almost no real-world API sends back Access-Control-Allow-Origin
+  // headers permitting an arbitrary docs site's origin, so the direct
+  // call fails for most real APIs - see the send handler and
+  // PROXY_BASE_URL in ApiReferencePanel.astro. Defaults to enabled; a
+  // site can set this to `false` to never involve a third party.
   proxy: z.boolean().default(true)
 }).strict().default({ proxy: true });
 const contextMenuSchema = z.object({
@@ -628,6 +625,7 @@ function createJsonLocator(rawText) {
   return criarLocalizador(rawText);
 }
 function criarLocalizador(rawText) {
+  rawText = semBom(rawText);
   let arvore;
   try {
     arvore = parseTree(rawText);
@@ -745,6 +743,7 @@ function humanizar(issue, raiz) {
   }
 }
 function unknownRootKeyIssues(rawText) {
+  rawText = semBom(rawText);
   let raiz;
   try {
     raiz = JSON.parse(rawText);
@@ -773,7 +772,11 @@ function unknownRootKeyIssues(rawText) {
     };
   });
 }
+function semBom(texto) {
+  return texto.charCodeAt(0) === 65279 ? texto.slice(1) : texto;
+}
 function validateDocsConfig(rawText) {
+  rawText = semBom(rawText);
   let raw;
   try {
     raw = JSON.parse(rawText);

package/src/lib/config-schema.ts

@@ -713,18 +713,15 @@ export const pageFrontmatterSchema = z.object({
 // about the spec itself.
 const apiSchema = z
   .object({
-    // Whether the Try-it modal's Send button routes its request through
-    // writedocs' own CORS proxy (https://proxy.writechoice.io/) rather
-    // than calling the API directly from the browser. Almost no
-    // real-world API sends back Access-Control-Allow-Origin headers
-    // permitting an arbitrary docs site's origin, so a direct browser
-    // fetch() from the Try-it modal fails for most real APIs without
-    // this - see PROXY_BASE_URL in ApiReferencePanel.astro for the
-    // actual request-forwarding logic. Defaults to enabled; a site can
-    // set this to `false` to always call the API directly instead (the
-    // API is already CORS-permissive, same-origin in some deployments,
-    // or the site owner doesn't want requests routed through a third
-    // party at all).
+    // Whether a Try-it request the browser blocks is retried through
+    // writedocs' own CORS proxy (https://proxy.writechoice.io/). The
+    // request always goes to the API directly first, so a reader's key
+    // reaches the proxy only when the API itself refuses browser calls.
+    // Almost no real-world API sends back Access-Control-Allow-Origin
+    // headers permitting an arbitrary docs site's origin, so the direct
+    // call fails for most real APIs - see the send handler and
+    // PROXY_BASE_URL in ApiReferencePanel.astro. Defaults to enabled; a
+    // site can set this to `false` to never involve a third party.
     proxy: z.boolean().default(true),
   })
   .strict()
@@ -1322,6 +1319,7 @@ export function createJsonLocator(rawText: string): (path: (string | number)[])
  *  quando o no nao existe no texto (campo obrigatorio ausente e o caso comum):
  *  `line` ausente e melhor que `line` inventada. */
 function criarLocalizador(rawText: string): (caminho: (string | number)[]) => { line: number; column: number } | null {
+  rawText = semBom(rawText);
   let arvore: ReturnType<typeof parseTree> | undefined;
   try {
     arvore = parseTree(rawText);
@@ -1485,6 +1483,7 @@ function humanizar(issue: IssuePlano, raiz: unknown): { humanMessage?: string; s
  *  porque a plataforma repassa `issues` como `errors` e um aviso ali viraria
  *  erro. */
 export function unknownRootKeyIssues(rawText: string): ValidationIssue[] {
+  rawText = semBom(rawText);
   let raiz: unknown;
   try {
     raiz = JSON.parse(rawText);
@@ -1516,7 +1515,16 @@ export function unknownRootKeyIssues(rawText: string): ValidationIssue[] {
     });
 }
 
+/** Texto sem o BOM do UTF-8 no inicio. Editores do Windows (Bloco de Notas, o
+ *  `Out-File` do PowerShell 5.1) gravam um, e o JSON.parse o rejeita com uma
+ *  mensagem que culpa virgulas e colchetes. Copia local, e nao import de
+ *  lib/config-file.js: este modulo so importa zod e jsonc-parser (ver o topo). */
+function semBom(texto: string): string {
+  return texto.charCodeAt(0) === 0xfeff ? texto.slice(1) : texto;
+}
+
 export function validateDocsConfig(rawText: string): ValidationResult {
+  rawText = semBom(rawText);
   let raw: unknown;
   try {
     raw = JSON.parse(rawText);