@writedocs/generator 0.4.8 → 0.4.10

package/src/lib/openapi-render.ts

@@ -11,6 +11,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { writedocsTempDir } from './writedocs-temp-dir.js';
+import { specDirName } from './openapi-ref.js';
 
 export interface OpenApiSchema {
   type?: string;
@@ -58,10 +59,18 @@ export function operationFileName(method: string, urlPath: string): string {
  *  every "operations" directory it finds for the target filename. Returns
  *  null if no group's spec defines this operation (a stale/typo'd
  *  `openapi:` frontmatter value). */
-export function findOperationFile(contentDir: string, method: string, urlPath: string): string | null {
+export function findOperationFile(contentDir: string, method: string, urlPath: string, spec?: string | null): string | null {
   const openapiRoot = path.join(writedocsTempDir(contentDir), 'openapi');
   const filename = operationFileName(method, urlPath);
 
+  // A page that names its spec (Mintlify's "spec.json METHOD /path" -
+  // see lib/openapi-ref.js) looks in that spec's own operations first, so
+  // the same METHOD /path in two specs resolves to the right one.
+  if (spec) {
+    const own = path.join(openapiRoot, '_pages', specDirName(spec), 'operations', filename);
+    if (fs.existsSync(own)) return own;
+  }
+
   function walk(dir: string): string | null {
     if (!fs.existsSync(dir)) return null;
     for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {

package/src/lib/pages.js

@@ -0,0 +1,150 @@
+// Which files in a content directory are pages. Plain JavaScript, not
+// TypeScript, so `writedocs validate` can load it with plain Node (Node
+// refuses to strip types under node_modules - see lib/icons.js's comment);
+// lib/config.ts re-exports findAllPages() for everything inside Astro.
+import fs from 'node:fs';
+import path from 'node:path';
+import matter from 'gray-matter';
+
+// Top-level folders of a content directory that are never scanned for
+// pages - build output, dependencies, and static assets. Any folder whose
+// name starts with a dot (.git, .github, .claude, .mintlify, ...) is
+// skipped too, at any depth - see findAllPages().
+export const EXCLUDED_TOP_LEVEL_DIRS = new Set(['node_modules', 'dist', '.astro', '.writedocs', 'public', '.git']);
+
+/** A page's title when its frontmatter has none - Mintlify's rule, so a
+ *  migrated page that relied on it keeps the same title: the file name
+ *  without its extension, dashes and underscores as spaces, first letter
+ *  capitalized. `guides/getting-started.mdx` -> "Getting started". */
+export function titleFromPath(filePath) {
+  const base = String(filePath).split(/[\\/]/).pop().replace(/\.mdx?$/i, '');
+  const words = base.replace(/[-_]+/g, ' ').trim();
+  return words ? words.charAt(0).toUpperCase() + words.slice(1) : 'Untitled';
+}
+
+/** Mintlify's .mintignore, if the content directory has one: gitignore-
+ *  style patterns for files and folders that aren't published. Supports
+ *  comments, blank lines, `*`, `**`, `?`, a leading `/` (anchored to the
+ *  content directory) and a trailing `/` (folders only); negation (`!`)
+ *  isn't supported and such lines are skipped. Returns (relPath, isDir) =>
+ *  boolean. */
+function readIgnoreFile(contentDir) {
+  let text;
+  try {
+    text = fs.readFileSync(path.join(contentDir, '.mintignore'), 'utf-8');
+  } catch {
+    return () => false;
+  }
+  const rules = text
+    .split(/\r?\n/)
+    .map((l) => l.trim())
+    .filter((l) => l && !l.startsWith('#') && !l.startsWith('!'))
+    .map((pattern) => {
+      const dirOnly = pattern.endsWith('/');
+      let p = pattern.replace(/\/+$/, '');
+      const anchored = p.startsWith('/') || p.includes('/');
+      p = p.replace(/^\/+/, '');
+      const source = p
+        .split(/(\*\*\/?|\*|\?)/)
+        .map((part) =>
+          part === '**/' || part === '**' ? '(?:.*/)?' : part === '*' ? '[^/]*' : part === '?' ? '[^/]' : part.replace(/[.+^${}()|[\]\\]/g, '\\$&')
+        )
+        .join('');
+      const re = new RegExp(anchored ? `^${source}$` : `(?:^|/)${source}$`);
+      return { re, dirOnly };
+    });
+  return (rel, isDir) => rules.some((r) => (!r.dirOnly || isDir) && r.re.test(rel));
+}
+
+/** Page ids writedocs.json's navigation lists (strings in arrays, and
+ *  groups' `page`) - read straight from the file, since this runs before
+ *  (and independently of) config validation. Empty when there's no
+ *  readable writedocs.json. */
+function navigationPageIds(contentDir) {
+  let config;
+  try {
+    config = JSON.parse(fs.readFileSync(path.join(contentDir, 'writedocs.json'), 'utf-8'));
+  } catch {
+    return new Set();
+  }
+  const ids = new Set();
+  (function walk(node) {
+    if (Array.isArray(node)) node.forEach((item) => (typeof item === 'string' ? ids.add(item) : walk(item)));
+    else if (node && typeof node === 'object') {
+      for (const [key, value] of Object.entries(node)) {
+        if (key === 'page' && typeof value === 'string') ids.add(value);
+        else if (key !== 'openapi' && key !== 'href') walk(value);
+      }
+    }
+  })(config.navigation);
+  return ids;
+}
+
+/** Recursively finds every .md/.mdx file under `contentDir` that is a page:
+ *  one with a frontmatter block, or one writedocs.json's navigation lists
+ *  (a Mintlify page needs no frontmatter at all - see titleFromPath()).
+ *  Skips EXCLUDED_TOP_LEVEL_DIRS, every dot-folder at any depth, and
+ *  anything a .mintignore file lists. docs/ is scanned exactly like any
+ *  other folder, no special-casing. Returns POSIX-relative paths (from
+ *  `contentDir`) suitable to hand straight to Astro's `glob()` loader as a
+ *  literal `pattern` array - see content.config.ts's `pages` collection,
+ *  and [...slug].astro, which needs the identical list to decide whether
+ *  calling `getCollection('pages')` is worth doing at all. Also reused by
+ *  astro.config.mjs's noindex/sitemap scan and by `writedocs validate`, so
+ *  all of them see exactly the same file set. Synchronous and re-run from
+ *  scratch wherever it's called - cheap enough for a docs site's file
+ *  count. */
+export function findAllPages(contentDir) {
+  const results = [];
+  const ignored = readIgnoreFile(contentDir);
+  const listed = navigationPageIds(contentDir);
+  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;
+        if (entry.name.startsWith('.')) continue;
+        if (ignored(rel, true)) continue;
+        walk(abs, rel);
+        continue;
+      }
+      if (!entry.isFile() || !/\.mdx?$/i.test(entry.name)) continue;
+      if (ignored(rel, false)) continue;
+      let raw;
+      try {
+        raw = fs.readFileSync(abs, 'utf-8');
+      } catch {
+        continue;
+      }
+      let data;
+      try {
+        ({ data } = matter(raw));
+      } catch {
+        // Frontmatter that isn't valid YAML: still a page (it opens a
+        // frontmatter block), so the error surfaces with this file's name -
+        // from `writedocs validate`, or Astro's own loader in the build -
+        // instead of as a bare YAML error thrown from here.
+        if (/^---\r?\n/.test(raw)) results.push(rel);
+        continue;
+      }
+      if (Object.keys(data).length === 0 && !listed.has(fileIdForPath(rel))) continue; // not a page
+      results.push(rel);
+    }
+  }
+  walk(contentDir, '');
+  return results;
+}
+
+/** The id writedocs.json's navigation refers to a page by: its path from
+ *  the content directory, without the extension or a trailing `/index`
+ *  (same algorithm as fileIdForEntry() in lib/config.ts). */
+export function fileIdForPath(relativePath) {
+  return relativePath.replace(/\.mdx?$/i, '').replace(/\/index$/, '');
+}

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

@@ -20,6 +20,7 @@ import {
   findAllPages,
 } from "../lib/config";
 import { writedocsTempDir } from "../lib/writedocs-temp-dir.js";
+import { parseOpenApiRef } from "../lib/openapi-ref.js";
 import BaseLayout from "../layout/BaseLayout.astro";
 import Sidebar from "../layout/components/Sidebar.astro";
 import TableOfContents from "../layout/components/TableOfContents.astro";
@@ -55,6 +56,8 @@ import Check from "../components/Check.astro";
 import ParamField from "../components/ParamField.astro";
 import ResponseField from "../components/ResponseField.astro";
 import Columns from "../components/Columns.astro";
+import Column from "../components/Column.astro";
+import CodeBlock from "../components/CodeBlock.astro";
 import Tooltip from "../components/Tooltip.astro";
 import Update from "../components/Update.astro";
 import Tile from "../components/Tile.astro";
@@ -321,8 +324,9 @@ for (const e of entries) {
   navTitleByFileId.set(fileId, e.data.sidebarTitle ?? e.data.title);
   entryByFileId.set(fileId, e);
   // `hideApiMarker` (Mintlify's) drops the badge for this one page.
-  if (e.data.openapi && !e.data.hideApiMarker) {
-    methodByFileId.set(fileId, e.data.openapi.trim().split(/\s+/, 1)[0].toUpperCase());
+  const apiRef = parseOpenApiRef(e.data.openapi);
+  if (apiRef && !e.data.hideApiMarker) {
+    methodByFileId.set(fileId, apiRef.method);
   }
 }
 const titleForSlug = (slug: string) => titleByFileId.get(slug) ?? slug;
@@ -444,6 +448,8 @@ const components = {
   ParamField,
   ResponseField,
   Columns,
+  Column,
+  CodeBlock,
   Tooltip,
   Update,
   Tile,