@writedocs/generator 0.7.2 → 0.7.4

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/llms-index.ts

@@ -0,0 +1,88 @@
+// llms.txt and its child files (/llms/*.md) - the pages an AI tool can
+// discover, in the site's navigation structure. Shared by llms.txt.ts (the
+// root file) and llms/[...path].md.ts (the child files a big site's llms.txt
+// links to), so both render from the same tree in the same run. The
+// structure and the splitting live in lib/llms.js.
+import { getCollection, type CollectionEntry } from 'astro:content';
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadDocsConfig, normalizeEntryId, findAllPages, resolveSiteUrl, fileIdForEntry } from './config';
+import { buildLlmsTree, renderLlmsFiles } from './llms.js';
+import { navigationPageOrder } from './pages.js';
+import { writedocsTempDir } from './writedocs-temp-dir.js';
+
+type DocsEntry = CollectionEntry<'pages'> | CollectionEntry<'generatedDocs'>;
+
+// Mirrors Mintlify's own llms.txt behavior: a page's frontmatter
+// `description` is cut at the first line break (a multi-paragraph
+// description would blow out a one-line list entry) and at 300 characters,
+// so every entry stays scannable.
+const DESCRIPTION_MAX_CHARS = 300;
+function truncateDescription(description: string | undefined): string | undefined {
+  if (!description) return undefined;
+  const firstLine = description.split('\n')[0].trim();
+  if (!firstLine) return undefined;
+  return firstLine.length > DESCRIPTION_MAX_CHARS ? firstLine.slice(0, DESCRIPTION_MAX_CHARS).trimEnd() + '…' : firstLine;
+}
+
+// Most characters one file holds - llms.txt or a child file. The llms.txt
+// spec sets no limit ("small enough to fit in context"); this is Mintlify's,
+// about 25,000 tokens. Past it, sections move into child files instead of
+// pages being dropped.
+export const LLMS_MAX_CHARS = 100_000;
+
+/** The generated files as Map<path, text> - 'llms.txt', then 'llms/<...>.md'
+ *  when the site needs them - or null when the project has its own
+ *  llms.txt, which replaces all of it. */
+export async function llmsIndexFiles(): Promise<Map<string, string> | null> {
+  const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
+  const packageRoot = process.env.WRITEDOCS_PACKAGE_ROOT || process.cwd();
+  // A hand-authored llms.txt at the project root (next to writedocs.json)
+  // wins outright - same override convention Mintlify documents.
+  if (fs.existsSync(path.join(contentDir, 'llms.txt'))) return null;
+
+  const config = loadDocsConfig(contentDir);
+  const siteUrl = resolveSiteUrl(config); // absolute origin if `domain` is set, else null
+
+  const hasGeneratedDocs = fs.existsSync(path.join(writedocsTempDir(contentDir), 'generated-docs'));
+  const hasPages = findAllPages(contentDir).length > 0;
+  const [pagesEntries, generatedDocsEntries] = await Promise.all([
+    hasPages ? getCollection('pages') : Promise.resolve([]),
+    hasGeneratedDocs ? getCollection('generatedDocs') : Promise.resolve([]),
+  ]);
+  const entries: DocsEntry[] = [...pagesEntries, ...generatedDocsEntries];
+
+  const pages = new Map<string, { title: string; href: string; description?: string; slug: string }>();
+  for (const entry of entries) {
+    // A page that opted out of search-engine indexing (`seo.noindex`, also
+    // left out of sitemap.xml) is left out here too, and a frontmatter `url`
+    // page (Mintlify's external link) has no content of its own.
+    if (entry.data.seo?.noindex || entry.data.url) continue;
+    const slug = normalizeEntryId(entry.id);
+    // The .md route when it exists ([...slug].md.ts - with `contextMenu`,
+    // and never for an OpenAPI page, which renders from the spec), else the
+    // HTML page.
+    const hasMarkdownRoute = config.contextMenu && !entry.data.openapi;
+    const href = (siteUrl ?? '') + (hasMarkdownRoute ? `/${slug}.md` : slug === 'index' ? '/' : `/${slug}/`);
+    let description = truncateDescription(entry.data.description);
+    // Mirrors Mintlify: an OpenAPI operation page's description gets its
+    // "METHOD /path" appended - the page itself renders from the spec.
+    if (entry.data.openapi) description = description ? `${description} (${entry.data.openapi})` : entry.data.openapi;
+    pages.set(fileIdForEntry(contentDir, packageRoot, entry), { title: entry.data.title, href, description, slug });
+  }
+
+  const listed = new Set(navigationPageOrder(config.navigation));
+  const unlisted = [...pages.entries()]
+    .filter(([id]) => !listed.has(id))
+    .sort((a, b) => a[1].slug.localeCompare(b[1].slug))
+    .map(([id]) => id);
+  const tree = buildLlmsTree(config.navigation, (id: string) => pages.get(id) ?? null, unlisted);
+
+  return renderLlmsFiles({
+    name: config.name,
+    description: config.description,
+    tree,
+    maxChars: LLMS_MAX_CHARS,
+    urlFor: (file: string) => `${siteUrl ?? ''}/${file}`,
+  });
+}

package/src/lib/llms.js

@@ -0,0 +1,200 @@
+// Shared by the llms routes (lib/llms-index.ts, llms-full.txt.ts): the order
+// pages appear in, and llms.txt's structure. Plain JavaScript, so it can be
+// tested with plain Node.
+import { navigationPageOrder } from './pages.js';
+
+/** `items` ({ fileId, slug }) in navigation order - the order a reader meets
+ *  the pages in the sidebar - then every page the navigation doesn't list,
+ *  by URL. */
+export function orderByNavigation(items, navigation) {
+  const rank = new Map(navigationPageOrder(navigation).map((id, i) => [id, i]));
+  const at = (item) => rank.get(item.fileId) ?? Infinity;
+  return [...items].sort((a, b) => at(a) - at(b) || a.slug.localeCompare(b.slug));
+}
+
+// --- llms.txt as a tree -------------------------------------------------
+//
+// llms.txt lists every page under headings that follow the navigation -
+// products, versions, languages, tabs, dropdowns, groups. A site too big for
+// one file (MAX_CHARS) keeps llms.txt as a directory: its largest sections
+// move into child files under /llms/, linked from where they were, and a
+// child too big is split the same way. No page is ever left out - the scheme
+// Mintlify moved to from cutting the list off
+// (https://www.mintlify.com/blog/scaling-llms-txt).
+
+const CONTAINERS = [
+  ['tabs', 'tab'],
+  ['versions', 'version'],
+  ['languages', 'language'],
+  ['dropdowns', 'dropdown'],
+  ['products', 'product'],
+];
+
+/** A Section: { label, items: [page], sections: [Section] }. `pageFor(id)`
+ *  gives a listed page ({ title, href, description }) or null for one that
+ *  isn't listed (noindex, an external `url`, missing). A page shows up once,
+ *  where the navigation first lists it; `unlisted` pages (not in the
+ *  navigation at all) go in a trailing "Other pages" section. */
+export function buildLlmsTree(navigation, pageFor, unlisted = []) {
+  const seen = new Set();
+  const page = (id) => {
+    if (seen.has(id)) return null;
+    const found = pageFor(id);
+    if (!found) return null;
+    seen.add(id);
+    return found;
+  };
+  const prune = (section) => section.items.length > 0 || section.sections.length > 0;
+
+  function fromList(list) {
+    const node = { items: [], sections: [] };
+    for (const item of list ?? []) {
+      if (typeof item === 'string') {
+        const p = page(item);
+        if (p) node.items.push(p);
+      } else if (item && typeof item === 'object' && typeof item.group === 'string' && Array.isArray(item.pages)) {
+        const own = typeof item.page === 'string' ? page(item.page) : null;
+        const inner = fromList(item.pages);
+        const section = { label: item.group, items: own ? [own, ...inner.items] : inner.items, sections: inner.sections };
+        if (prune(section)) node.sections.push(section);
+      }
+      // A link leaf ({ href }) isn't a page of this site.
+    }
+    return node;
+  }
+
+  function fromContainer(container) {
+    if (Array.isArray(container)) return fromList(container);
+    if (!container || typeof container !== 'object') return { items: [], sections: [] };
+    if (Array.isArray(container.pages)) return fromList(container.pages);
+    for (const [key, labelKey] of CONTAINERS) {
+      if (!Array.isArray(container[key])) continue;
+      const sections = container[key]
+        .filter((child) => child && typeof child === 'object' && !('href' in child))
+        .map((child) => {
+          const label = labelKey === 'version' || labelKey === 'language' ? child.label ?? child[labelKey] : child[labelKey];
+          return { label: String(label), ...fromContainer(child) };
+        })
+        .filter(prune);
+      return { items: [], sections };
+    }
+    return { items: [], sections: [] };
+  }
+
+  const root = fromContainer(navigation);
+  for (const dropdown of (!Array.isArray(navigation) && navigation?.global?.dropdowns) || []) {
+    if ('href' in dropdown) continue;
+    const section = { label: String(dropdown.dropdown), ...fromContainer(dropdown) };
+    if (prune(section)) root.sections.push(section);
+  }
+  const rest = unlisted.map((id) => page(id)).filter(Boolean);
+  if (rest.length) root.sections.push({ label: 'Other pages', items: rest, sections: [] });
+  return root;
+}
+
+const pageLine = (p) => `- [${p.title}](${p.href})${p.description ? `: ${p.description}` : ''}`;
+const countPages = (s) => s.items.length + s.sections.reduce((n, c) => n + countPages(c), 0);
+const heading = (depth, label) => `${'#'.repeat(Math.min(depth, 6))} ${label}`;
+
+function slugify(label) {
+  return String(label).toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '') || 'section';
+}
+
+/** The body of `node` as Markdown lines: its pages, then each sub-section -
+ *  under its own heading, or, when it's in `split`, as a link to its file. */
+function renderBody(node, depth, split) {
+  const lines = [];
+  if (node.items.length) lines.push(...node.items.map(pageLine), '');
+  for (const section of node.sections) {
+    lines.push(heading(depth, section.label), '');
+    const file = split.get(section);
+    if (file) {
+      const n = countPages(section);
+      lines.push(`- [${section.label}](${file.url}): ${n} page${n === 1 ? '' : 's'}, listed in their own file`, '');
+    } else {
+      lines.push(...renderBody(section, depth + 1, split));
+    }
+  }
+  return lines;
+}
+
+const render = (header, node, depth, split) => [...header, ...renderBody(node, depth, split)].join('\n').replace(/\n{3,}/g, '\n\n').trimEnd() + '\n';
+
+/** Every section inside `node` still rendered inline (not split, and not
+ *  inside a split one), with the characters it takes. */
+function inlineSections(node, depth, split, out = []) {
+  for (const section of node.sections) {
+    if (split.has(section)) continue;
+    out.push({ section, size: render([], { items: [], sections: [section] }, depth, split).length });
+    inlineSections(section, depth + 1, split, out);
+  }
+  return out;
+}
+
+/** A section whose own page list alone is too big becomes parts, each a
+ *  sub-section small enough for a file of its own. */
+function chunkItems(node, maxChars, label) {
+  const budget = Math.max(1000, maxChars - 2000);
+  const parts = [];
+  let current = [];
+  let size = 0;
+  for (const p of node.items) {
+    const n = pageLine(p).length + 1;
+    if (current.length && size + n > budget) {
+      parts.push(current);
+      current = [];
+      size = 0;
+    }
+    current.push(p);
+    size += n;
+  }
+  if (current.length) parts.push(current);
+  // One part is the list as it was - nothing smaller to split into (a single
+  // page line longer than the budget). Leave it, rather than loop.
+  if (parts.length < 2) return [];
+  const sections = parts.map((items, i) => ({ label: `${label} (part ${i + 1} of ${parts.length})`, items, sections: [] }));
+  node.sections = [...sections, ...node.sections];
+  node.items = [];
+  return sections;
+}
+
+/** llms.txt, and any child files it needs, as Map<path, text>: 'llms.txt',
+ *  then e.g. 'llms/core-platform.md'. `urlFor(path)` gives a file's URL. */
+export function renderLlmsFiles({ name, description, tree, maxChars, urlFor }) {
+  const files = new Map();
+  const taken = new Set(['llms.txt']);
+  const rootUrl = urlFor('llms.txt');
+
+  function emit(filePath, header, node, depth, trail) {
+    const split = new Map();
+    const splitOut = (section) => {
+      const dir = filePath === 'llms.txt' ? 'llms' : filePath.replace(/\.md$/, '');
+      let childPath = `${dir}/${slugify(section.label)}.md`;
+      for (let n = 2; taken.has(childPath); n++) childPath = `${dir}/${slugify(section.label)}-${n}.md`;
+      taken.add(childPath);
+      split.set(section, { path: childPath, url: urlFor(childPath) });
+    };
+    // A page list too long for this file on its own becomes parts - all of
+    // them separate files, so this one is a plain list of the parts.
+    if (render(header, { items: node.items, sections: [] }, depth, split).length > maxChars) {
+      chunkItems(node, maxChars, trail.length ? trail[trail.length - 1] : 'Pages').forEach(splitOut);
+    }
+    // Then the biggest sections move out, one at a time, until this fits.
+    while (render(header, node, depth, split).length > maxChars) {
+      const candidates = inlineSections(node, depth, split);
+      if (!candidates.length) break;
+      splitOut(candidates.reduce((a, b) => (b.size > a.size ? b : a)).section);
+    }
+    files.set(filePath, render(header, node, depth, split));
+    for (const [section, file] of split) {
+      const childTrail = [...trail, section.label];
+      const childHeader = [`# ${name}: ${childTrail.join(' > ')}`, '', `> Part of the ${name} docs index: ${rootUrl}`, ''];
+      emit(file.path, childHeader, section, 2, childTrail);
+    }
+  }
+
+  const header = [`# ${name}`, ''];
+  if (description) header.push(`> ${description}`, '');
+  emit('llms.txt', header, tree, 2, []);
+  return files;
+}

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