@writedocs/generator 0.7.2 → 0.7.3

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

package/src/scripts/search.ts

@@ -1,17 +1,33 @@
 // SearchModal.astro's own trigger button (rendered inside TopBar.astro) +
 // overlay/modal. Owns opening/closing the modal, the ⌘K/Ctrl K shortcut,
 // lazy-loading Pagefind on first open, and rendering results.
+
+// The current page's modal, for the ⌘K/Ctrl K shortcut. ClientRouter swaps
+// in a new modal on every navigation and initSearch() runs again for it; the
+// shortcut is one document listener, attached once, that always acts on
+// this. (Attached per page, it piled up one listener per visited page, each
+// still driving that page's detached modal - on a page without a modal of
+// its own, Ctrl K then locked the page's scrolling.)
+let active: { toggle(): void; closeIfOpen(): void } | null = null;
+let shortcutBound = false;
+
 export function initSearch(root: ParentNode) {
+  // No trigger button on a `blank` page (no topbar) - the modal and its
+  // shortcut still work there, as BaseLayout.astro intends.
   const trigger = root.querySelector<HTMLButtonElement>('[data-search-trigger]');
   const overlay = root.querySelector<HTMLElement>('#wd-search-overlay');
   const input = root.querySelector<HTMLInputElement>('#wd-search-input');
   const resultsEl = root.querySelector<HTMLElement>('#wd-search-results');
-  if (!trigger || !overlay || !input || !resultsEl || trigger.dataset.wdInit) return;
-  trigger.dataset.wdInit = 'true';
+  if (!overlay || !input || !resultsEl) {
+    active = null;
+    return;
+  }
+  if (overlay.dataset.wdInit) return;
+  overlay.dataset.wdInit = 'true';
 
   // Most keyboards outside macOS/iOS don't have a command key - "Ctrl K"
   // reads more naturally there than the ⌘ glyph.
-  const kbd = trigger.querySelector('.wd-search-kbd');
+  const kbd = trigger?.querySelector('.wd-search-kbd');
   if (kbd && !/Mac|iPhone|iPad/.test(navigator.userAgent)) {
     kbd.textContent = 'Ctrl K';
   }
@@ -122,10 +138,10 @@ export function initSearch(root: ParentNode) {
   function close() {
     overlay.hidden = true;
     document.body.style.overflow = '';
-    trigger.focus();
+    trigger?.focus();
   }
 
-  trigger.addEventListener('click', open);
+  trigger?.addEventListener('click', open);
   overlay.addEventListener('click', (e) => {
     if (e.target === overlay) close();
   });
@@ -143,13 +159,22 @@ export function initSearch(root: ParentNode) {
       close();
     }
   });
-  document.addEventListener('keydown', (e) => {
-    if ((e.key === 'k' || e.key === 'K') && (e.metaKey || e.ctrlKey)) {
-      e.preventDefault();
-      if (overlay.hidden) open();
-      else close();
-    } else if (e.key === 'Escape' && !overlay.hidden) {
-      close();
-    }
-  });
+  active = {
+    toggle: () => (overlay.hidden ? open() : close()),
+    closeIfOpen: () => {
+      if (!overlay.hidden) close();
+    },
+  };
+  if (!shortcutBound) {
+    shortcutBound = true;
+    document.addEventListener('keydown', (e) => {
+      if (!active) return;
+      if ((e.key === 'k' || e.key === 'K') && (e.metaKey || e.ctrlKey)) {
+        e.preventDefault();
+        active.toggle();
+      } else if (e.key === 'Escape') {
+        active.closeIfOpen();
+      }
+    });
+  }
 }

package/writedocs.schema.json

@@ -692,8 +692,8 @@
         "proxy": {
           "default": true,
           "type": "boolean",
-          "description": "Send \"Try it\" requests through writedocs' proxy, for APIs that don't allow calls from other sites (CORS). Default true.",
-          "markdownDescription": "Send \"Try it\" requests through writedocs' proxy, for APIs that don't allow calls from other sites (CORS). Default true."
+          "description": "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.",
+          "markdownDescription": "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."
         }
       },
       "additionalProperties": false,