@writedocs/generator 0.7.1 → 0.7.3

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);

package/src/lib/config.ts

@@ -3,6 +3,7 @@ import path from 'node:path';
 import { EXCLUDED_TOP_LEVEL_DIRS } from './pages.js';
 import matter from 'gray-matter';
 import { writedocsTempDir } from './writedocs-temp-dir.js';
+import { readableTextOn } from './color.js';
 import {
   formatValidationIssues,
   validateDocsConfig,
@@ -208,13 +209,12 @@ export function resolveNavbarColor(
   return { background: value.background, accent: value.accent };
 }
 
-/** Picks black or white text for readable contrast against `hexColor`,
- *  via the standard relative-luminance formula (ITU-R BT.601 weights -
- *  the same "perceived brightness" approximation used all over the web
- *  for exactly this "what text color goes on this swatch" problem, not
- *  the more expensive WCAG relative-luminance formula, which isn't
- *  needed for a binary choose-the-less-bad-option decision like this
- *  one). Used two ways in BaseLayout.astro: for `--wd-navbar-accent-text`
+/** Picks black or white text for `hexColor` - white unless white falls
+ *  below 3:1 on it (readableTextOn() in lib/color.js), the same rule and
+ *  WCAG math `writedocs a11y` checks with, so the check measures what the
+ *  site renders. (This used a BT.601 brightness threshold.) Also
+ *  gives `--wd-on-primary`, the text on step numbers, the info banner and
+ *  the API playground's buttons. Used two ways in BaseLayout.astro: for `--wd-navbar-accent-text`
  *  (the active tab's own fill used to always be `var(--wd-primary)` with
  *  hardcoded `color: #fff`, which only actually read fine because every
  *  default/example primary color so far has been dark/saturated enough
@@ -224,19 +224,12 @@ export function resolveNavbarColor(
  *  hold unconditionally), and for `--wd-navbar-foreground` itself once
  *  `styles.navbar` is configured at all (the navbar's plain text/icon
  *  color - see `navbar`'s own schema comment for why that's always
- *  computed, never a writedocs.json value). Malformed input (not a 6-digit
- *  `#rrggbb` hex) falls back to white rather than throwing - same "don't
+ *  computed, never a writedocs.json value). Malformed input (not a
+ *  `#rgb`/`#rrggbb` hex) falls back to white rather than throwing - same "don't
  *  fail a build over a cosmetic color value" posture every other color
  *  field here takes (none of them validate hex syntax either). */
 export function contrastTextColor(hexColor: string): '#000000' | '#ffffff' {
-  const match = /^#?([0-9a-f]{6})$/i.exec(hexColor.trim());
-  if (!match) return '#ffffff';
-  const hex = match[1];
-  const r = parseInt(hex.slice(0, 2), 16);
-  const g = parseInt(hex.slice(2, 4), 16);
-  const b = parseInt(hex.slice(4, 6), 16);
-  const luminance = (299 * r + 587 * g + 114 * b) / 1000;
-  return luminance > 150 ? '#000000' : '#ffffff';
+  return readableTextOn(hexColor) as '#000000' | '#ffffff';
 }
 
 /** Whether an href points off-site - has an explicit scheme (`https:`,
@@ -481,122 +474,9 @@ export function loadDocsConfig(contentDir: string): DocsConfig {
 // JavaScript, so `writedocs validate` can find a site's pages with plain Node.
 export { findAllPages } from './pages.js';
 
-/** Any `.css`/`.js` file anywhere in the project - root or any subfolder,
- *  `public/` included - auto-loaded site-wide with zero `writedocs.json`
- *  config, on top of (not instead of) the explicit `scripts` field
- *  (bannerSchema and friends, above). Drop a file in, it loads;
- *  there's no field naming which ones to use, matching the same "just
- *  works" convention `docs/`'s own file discovery already follows (see
- *  findAllPages() above / `content-pipeline.mdx`) - a site author already
- *  drops content files in and expects them found, rather than also
- *  listing every one in writedocs.json.
- *
- *  Two separate walks, because `public/` needs different treatment than
- *  everywhere else:
- *
- *  - `css`/`js`: every `.css`/`.js` file outside `public/` (root, `docs/`,
- *    `snippets/`, any custom folder) - reused as the walk-with-exclusions
- *    shape from findAllPages() above, and its exact `EXCLUDED_TOP_LEVEL_DIRS`
- *    set (skipped only at the project root, same as there), so `dist/`,
- *    `node_modules/`, `.astro/`, `.writedocs/`, `.git/`, and (for this
- *    half only - see below) `public/` are never walked into. BaseLayout.astro
- *    reads each one's raw content and inlines it as a `<style>`/
- *    `<script is:inline>` tag.
- *  - `publicCss`/`publicJs`: every `.css`/`.js` file *inside* `public/`,
- *    walked separately (starting from `<contentDir>/public` rather than
- *    `contentDir` itself, so the same `EXCLUDED_TOP_LEVEL_DIRS` check
- *    doesn't apply here - there's no `public/public/` or `public/dist/`
- *    convention to guard against). Returned as public-URL-rooted hrefs
- *    (a leading `/`, no `public` segment - `public/custom.css` becomes
- *    `/custom.css`) rather than content-dir-relative paths, since these
- *    files are already served as static assets at exactly that URL once
- *    Astro copies `public/` into the build output. BaseLayout.astro
- *    renders these as ordinary `<link rel="stylesheet">`/`<script src>`
- *    tags pointing at that URL instead of inlining their content -
- *    inlining would duplicate every byte (once in the page's own HTML,
- *    once more as the independently-fetchable static file at that same
- *    URL) for no benefit, where a `<link>`/`<script src>` gets normal
- *    browser caching across pages instead of repeating the content on
- *    every single page's markup.
- *
- *  Both halves are broader than they might sound - a stray `.js` file
- *  kept in `docs/`, `snippets/`, or `public/` for an unrelated reason
- *  (a snippet's own local helper, an image gallery's lightbox script
- *  someone dropped in `public/` to reference from a raw `<script src>`
- *  in an .mdx file, say) gets auto-injected sitewide the same as a
- *  deliberate one; there's no separate "this one's just tooling" signal
- *  to opt out of the convention short of renaming its extension.
- *
- *  Both `css`/`js` and `publicCss`/`publicJs` are sorted alphabetically
- *  by their respective path for deterministic load order across rebuilds
- *  - same reasoning as llms.txt's own alphabetical-by-slug sort (see
- *  llms.txt.ts) - filesystem readdir order isn't guaranteed portable
- *  across OSes or directory-walk order otherwise.
- *
- *  `css`/`js` return POSIX-separated paths relative to `contentDir`, not
- *  absolute paths or file contents - BaseLayout.astro (the sole caller)
- *  resolves and reads each one's content itself, right before inlining
- *  it, so a file's content is always current as of that specific
- *  request/build rather than cached here across a `writedocs dev`
- *  session. `publicCss`/`publicJs` return the public-URL hrefs described
- *  above - nothing to read, Astro's own static-file serving/copy already
- *  handles those. */
-export function findRootAssets(
-  contentDir: string
-): { css: string[]; js: string[]; publicCss: string[]; publicJs: string[] } {
-  const css: string[] = [];
-  const js: string[] = [];
-  function walk(dir: string, relBase: string) {
-    let entries: fs.Dirent[];
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
-      const abs = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        if (relBase === '' && EXCLUDED_TOP_LEVEL_DIRS.has(entry.name)) continue;
-        walk(abs, rel);
-        continue;
-      }
-      if (!entry.isFile()) continue;
-      if (/\.css$/i.test(entry.name)) css.push(rel);
-      else if (/\.js$/i.test(entry.name)) js.push(rel);
-    }
-  }
-  walk(contentDir, '');
-  css.sort();
-  js.sort();
-
-  const publicCss: string[] = [];
-  const publicJs: string[] = [];
-  function walkPublic(dir: string, relBase: string) {
-    let entries: fs.Dirent[];
-    try {
-      entries = fs.readdirSync(dir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
-      const abs = path.join(dir, entry.name);
-      if (entry.isDirectory()) {
-        walkPublic(abs, rel);
-        continue;
-      }
-      if (!entry.isFile()) continue;
-      if (/\.css$/i.test(entry.name)) publicCss.push(`/${rel}`);
-      else if (/\.js$/i.test(entry.name)) publicJs.push(`/${rel}`);
-    }
-  }
-  walkPublic(path.join(contentDir, 'public'), '');
-  publicCss.sort();
-  publicJs.sort();
-
-  return { css, js, publicCss, publicJs };
-}
+// findRootAssets() lives in lib/pages.js - plain JavaScript, so it can be
+// tested with plain Node, next to findAllPages() whose exclusions it shares.
+export { findRootAssets } from './pages.js';
 
 /** The root-relative URL paths (leading `/`, e.g. `/images/hero.svg`)
  *  referenced by the writedocs.json/styles fields that point at a static asset
@@ -615,7 +495,7 @@ export function findRootAssets(
  *  `public/` was the one place `styles.background.images` (etc.) had to
  *  live, since Astro's own `publicDir` copy is the only thing that ever
  *  served them; everywhere else in this codebase's own "drop a file
- *  anywhere, it's found" convention (`findRootAssets()` right above,
+ *  anywhere, it's found" convention (`findRootAssets()` in lib/pages.js,
  *  `findAllPages()` for content) already worked project-wide. See that
  *  integration's own comment for the actual resolution mechanism (a dev-time
  *  middleware plus a post-build copy step, not a duplicated `publicDir`)
@@ -733,7 +613,10 @@ export function fileIdForEntry(
   const absoluteContentDir = path.resolve(contentDir);
   const absoluteFilePath = path.resolve(packageRoot, entry.filePath);
   const relativeToContentDir = path.relative(absoluteContentDir, absoluteFilePath);
-  if (relativeToContentDir.startsWith('..')) return entry.id;
+  // Outside contentDir: `..`-prefixed, or - on Windows, when the file is on
+  // another drive (temp on C:, project on D:) - an absolute path, since
+  // path.relative() can't bridge drives.
+  if (relativeToContentDir.startsWith('..') || path.isAbsolute(relativeToContentDir)) return entry.id;
   const posixRelative = relativeToContentDir.split(path.sep).join('/');
   if (EXCLUDED_TOP_LEVEL_DIRS.has(posixRelative.split('/')[0])) return entry.id;
   return posixRelative.replace(/\.mdx?$/i, '').replace(/\/index$/, '');

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

@@ -155,7 +155,7 @@ export const DESCRIPTIONS = {
   ...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.',
+  'api.proxy': 'When the browser blocks a "Try it" request (the API doesn\'t allow calls from other sites - CORS), retry it through writedocs\' proxy. Requests always go to the API directly first. 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.',

package/src/lib/mintlify-convert.js

@@ -11,6 +11,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { iconExists } from './icons.js';
+import { readJsonText } from './config-file.js';
 
 // ---------------------------------------------------------------------
 // Reading docs.json
@@ -28,7 +29,7 @@ export function loadMintlifyConfig(file) {
     if (seen.has(abs)) throw new Error(`Circular $ref: ${path.relative(root, abs)}`);
     seen.add(abs);
     try {
-      return resolve(JSON.parse(fs.readFileSync(abs, 'utf-8')), path.dirname(abs));
+      return resolve(JSON.parse(readJsonText(abs)), path.dirname(abs));
     } finally {
       seen.delete(abs);
     }

package/src/lib/pages.js

@@ -5,6 +5,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import matter from 'gray-matter';
+import { readConfigText } from './config-file.js';
 
 // Top-level folders of a content directory that are never scanned for
 // pages - build output, dependencies, and static assets. Any folder whose
@@ -63,7 +64,7 @@ function readIgnoreFile(contentDir) {
 function navigationPageIds(contentDir) {
   let config;
   try {
-    config = JSON.parse(fs.readFileSync(path.join(contentDir, 'writedocs.json'), 'utf-8'));
+    config = JSON.parse(readConfigText(contentDir));
   } catch {
     return new Set();
   }
@@ -148,3 +149,122 @@ export function findAllPages(contentDir) {
 export function fileIdForPath(relativePath) {
   return relativePath.replace(/\.mdx?$/i, '').replace(/\/index$/, '');
 }
+
+/** Any `.css`/`.js` file anywhere in the project - root or any subfolder,
+ *  `public/` included - auto-loaded site-wide with zero `writedocs.json`
+ *  config, on top of (not instead of) the explicit `scripts` field
+ *  (bannerSchema and friends, above). Drop a file in, it loads;
+ *  there's no field naming which ones to use, matching the same "just
+ *  works" convention `docs/`'s own file discovery already follows (see
+ *  findAllPages() above / `content-pipeline.mdx`) - a site author already
+ *  drops content files in and expects them found, rather than also
+ *  listing every one in writedocs.json.
+ *
+ *  Two separate walks, because `public/` needs different treatment than
+ *  everywhere else:
+ *
+ *  - `css`/`js`: every `.css`/`.js` file outside `public/` (root, `docs/`,
+ *    `snippets/`, any custom folder) - reused as the walk-with-exclusions
+ *    shape from findAllPages() above, and its exact `EXCLUDED_TOP_LEVEL_DIRS`
+ *    set (skipped only at the project root, same as there), so `dist/`,
+ *    `node_modules/`, `.astro/`, `.writedocs/`, `.git/`, and (for this
+ *    half only - see below) `public/` are never walked into. BaseLayout.astro
+ *    reads each one's raw content and inlines it as a `<style>`/
+ *    `<script is:inline>` tag.
+ *  - `publicCss`/`publicJs`: every `.css`/`.js` file *inside* `public/`,
+ *    walked separately (starting from `<contentDir>/public` rather than
+ *    `contentDir` itself, so the same `EXCLUDED_TOP_LEVEL_DIRS` check
+ *    doesn't apply here - there's no `public/public/` or `public/dist/`
+ *    convention to guard against). Returned as public-URL-rooted hrefs
+ *    (a leading `/`, no `public` segment - `public/custom.css` becomes
+ *    `/custom.css`) rather than content-dir-relative paths, since these
+ *    files are already served as static assets at exactly that URL once
+ *    Astro copies `public/` into the build output. BaseLayout.astro
+ *    renders these as ordinary `<link rel="stylesheet">`/`<script src>`
+ *    tags pointing at that URL instead of inlining their content -
+ *    inlining would duplicate every byte (once in the page's own HTML,
+ *    once more as the independently-fetchable static file at that same
+ *    URL) for no benefit, where a `<link>`/`<script src>` gets normal
+ *    browser caching across pages instead of repeating the content on
+ *    every single page's markup.
+ *
+ *  Both halves are broader than they might sound - a stray `.js` file
+ *  kept in `docs/`, `snippets/`, or `public/` for an unrelated reason
+ *  (a snippet's own local helper, an image gallery's lightbox script
+ *  someone dropped in `public/` to reference from a raw `<script src>`
+ *  in an .mdx file, say) gets auto-injected sitewide the same as a
+ *  deliberate one; there's no separate "this one's just tooling" signal
+ *  to opt out of the convention short of renaming its extension.
+ *
+ *  Both `css`/`js` and `publicCss`/`publicJs` are sorted alphabetically
+ *  by their respective path for deterministic load order across rebuilds
+ *  - same reasoning as llms.txt's own alphabetical-by-slug sort (see
+ *  llms.txt.ts) - filesystem readdir order isn't guaranteed portable
+ *  across OSes or directory-walk order otherwise.
+ *
+ *  `css`/`js` return POSIX-separated paths relative to `contentDir`, not
+ *  absolute paths or file contents - BaseLayout.astro (the sole caller)
+ *  resolves and reads each one's content itself, right before inlining
+ *  it, so a file's content is always current as of that specific
+ *  request/build rather than cached here across a `writedocs dev`
+ *  session. `publicCss`/`publicJs` return the public-URL hrefs described
+ *  above - nothing to read, Astro's own static-file serving/copy already
+ *  handles those. */
+export function findRootAssets(contentDir) {
+  const css = [];
+  const js = [];
+  function walk(dir, relBase) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        if (relBase === '' && EXCLUDED_TOP_LEVEL_DIRS.has(entry.name)) continue;
+        // Dot-folders (.github, .claude, .husky, .vscode, ...) hold tooling,
+        // never site assets - the same rule findAllPages() applies to pages.
+        // Without it, a CI script under .github/ ran on every page.
+        if (entry.name.startsWith('.')) continue;
+        walk(abs, rel);
+        continue;
+      }
+      if (!entry.isFile() || entry.name.startsWith('.')) continue; // .eslintrc.js and friends
+      if (/\.css$/i.test(entry.name)) css.push(rel);
+      else if (/\.js$/i.test(entry.name)) js.push(rel);
+    }
+  }
+  walk(contentDir, '');
+  css.sort();
+  js.sort();
+
+  const publicCss = [];
+  const publicJs = [];
+  function walkPublic(dir, relBase) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const rel = relBase ? `${relBase}/${entry.name}` : entry.name;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        walkPublic(abs, rel);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (/\.css$/i.test(entry.name)) publicCss.push(`/${rel}`);
+      else if (/\.js$/i.test(entry.name)) publicJs.push(`/${rel}`);
+    }
+  }
+  walkPublic(path.join(contentDir, 'public'), '');
+  publicCss.sort();
+  publicJs.sort();
+
+  return { css, js, publicCss, publicJs };
+}

package/src/lib/styles-asset-integration.js

@@ -56,6 +56,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { loadDocsConfig, collectConfiguredAssetPaths } from './config.ts';
+import { resolveOutsidePublic } from './asset-path.js';
 
 const MIME_BY_EXTENSION = {
   '.svg': 'image/svg+xml',
@@ -76,24 +77,6 @@ function mimeFor(filePath) {
   return MIME_BY_EXTENSION[path.extname(filePath).toLowerCase()] || 'application/octet-stream';
 }
 
-/** 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/.
- *  Segment-by-segment path-traversal guard (no
- *  `..`/`.` segments) since `urlPath` ultimately comes from an incoming
- *  request URL in the dev-server case, not just trusted writedocs.json
- *  content. Returns an absolute path, or null if nothing real is there. */
-function resolveOutsidePublic(urlPath, contentDir) {
-  const segments = urlPath.replace(/^\/+/, '').split('/');
-  if (segments.some((segment) => segment === '..' || segment === '.' || segment === '')) return null;
-  const absolute = path.join(contentDir, ...segments);
-  try {
-    return fs.statSync(absolute).isFile() ? absolute : null;
-  } catch {
-    return null;
-  }
-}
 
 function publicPathFor(urlPath, contentDir) {
   const segments = urlPath.replace(/^\/+/, '').split('/');

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

@@ -18,12 +18,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import matter from 'gray-matter';
 import { iconExists } from './icons.js';
+import { readJsonText } from './config-file.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'));
+  return JSON.parse(readJsonText(file));
 }
 
 const PAGE_ENDINGS = ['.api.mdx', '.info.mdx', '.mdx', '.md'];

package/src/pages/[...slug].astro

@@ -271,7 +271,11 @@ interface Props {
 
 const rawProps = Astro.props as Props;
 if (rawProps.redirectTo) {
-  return Astro.redirect(rawProps.redirectTo);
+  // 301, not Astro's default 302: in a static build the status only picks
+  // the meta refresh delay (astro/dist/core/routing/3xx.js) - 2 seconds of
+  // "Redirecting from..." text for a 302, none for a 301. Hosts that read
+  // _redirects get a real 301 for "/" too (write-redirects-file.js).
+  return Astro.redirect(rawProps.redirectTo, 301);
 }
 const {
   entry,
@@ -365,6 +369,11 @@ const activePagePosition = flattenNav(activeSection.pages).findIndex((e) => e.sl
 // plus the always-visible global dropdown list - see BaseLayout.astro
 // for how each renders.
 const selectors = buildSelectors(activeSection.path, hrefForSlug, activePagePosition);
+// <html lang>: the `language` of the navigation level this page sits under,
+// if any. A hidden page has no level of its own (activeSection is only a
+// fallback for its chrome), so it keeps the default.
+const languageSegment = isHidden ? undefined : activeSection.path.find((segment) => segment.kind === "language");
+const pageLang = languageSegment ? (languageSegment.items[languageSegment.index] as { language: string }).language : undefined;
 const globalDropdowns = buildGlobalDropdowns(
   resolveGlobalDropdowns(config.navigation),
   currentFileId,
@@ -473,6 +482,7 @@ const components = {
   selectors={selectors}
   globalDropdowns={globalDropdowns}
   mode={pageMode}
+  lang={pageLang}
 >
   {showSidebar && <Sidebar slot="sidebar" navTree={navTree} hrefForSlug={hrefForSlug} currentSlug={currentFileId} />}
   {

package/src/pages/llms.txt.ts

@@ -94,7 +94,11 @@ export const GET: APIRoute = async () => {
       // hrefForSlug() in [...slug].astro for the HTML form, and
       // [...slug].md.ts for the .md form (no trailing slash, "index.md"
       // for the home page rather than the HTML convention's bare "/").
-      const path_ = config.contextMenu ? `/${slug}.md` : slug === 'index' ? '/' : `/${slug}/`;
+      // An OpenAPI operation page has no .md form ([...slug].md.ts leaves
+      // it out - it renders from the spec, not prose), so it keeps its HTML
+      // URL even when the .md routes exist.
+      const hasMarkdownRoute = config.contextMenu && !entry.data.openapi;
+      const path_ = hasMarkdownRoute ? `/${slug}.md` : slug === 'index' ? '/' : `/${slug}/`;
       const href = (siteUrl ?? '') + path_;
       let description = truncateDescription(entry.data.description);
       // Mirrors Mintlify's own behavior: an OpenAPI operation page's