@writedocs/generator 0.4.7 → 0.4.8

package/src/lib/inline-markdown.js

@@ -0,0 +1,29 @@
+// A string prop rendered with the small subset of inline Markdown Mintlify
+// allows in some component props (Tile's `title`, Prompt's `description`,
+// Color.Row's `title`): `code`, **bold**, and *italic* / _italic_. The
+// input is HTML-escaped first, so this is always safe to hand to set:html -
+// nothing in a prop value can produce markup other than these three.
+
+function escapeHtml(value) {
+  return value
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
+export function inlineMarkdown(value) {
+  if (!value) return '';
+  // Code spans first, and set aside, so ** or _ inside them stay literal.
+  const codeSpans = [];
+  let html = escapeHtml(String(value)).replace(/`([^`]+)`/g, (_, code) => {
+    codeSpans.push(`<code>${code}</code>`);
+    return `\u0000${codeSpans.length - 1}\u0000`;
+  });
+  html = html
+    .replace(/\*\*([^*]+)\*\*/g, '<strong>$1</strong>')
+    .replace(/(^|[^\w*])\*([^*]+)\*(?!\w)/g, '$1<em>$2</em>')
+    .replace(/(^|[^\w])_([^_]+)_(?!\w)/g, '$1<em>$2</em>');
+  return html.replace(/\u0000(\d+)\u0000/g, (_, i) => codeSpans[Number(i)]);
+}

package/src/lib/mdx-inject-builtins.js

@@ -39,6 +39,16 @@ const BUILTIN_COMPONENT_NAMES = [
   'ResponseField',
   'Columns',
   'Tooltip',
+  'Update',
+  'Tile',
+  'Panel',
+  'Prompt',
+  'View',
+  'Visibility',
+  'Tree',
+  'FileTree',
+  'Color',
+  'GitHub',
 ];
 
 const PACKAGE_SPECIFIER = 'writedocs/components';
@@ -77,8 +87,11 @@ export function remarkInjectBuiltinComponents() {
     const needed = new Set();
     visit(tree, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (node) => {
       if (!node.name) return;
-      if (BUILTIN_COMPONENT_NAMES.includes(node.name) && !locallyBound.has(node.name)) {
-        needed.add(node.name);
+      // A dotted name (<Tree.File>, <GitHub.Repo>) needs its root imported -
+      // the parts hang off it (see src/components/compound.ts).
+      const root = node.name.split('.')[0];
+      if (BUILTIN_COMPONENT_NAMES.includes(root) && !locallyBound.has(root)) {
+        needed.add(root);
       }
     });
 

package/src/lib/mdx-mintlify.js

@@ -0,0 +1,99 @@
+import { visit } from 'unist-util-visit';
+
+// Remark plugins for Mintlify components whose input can't be read from a
+// component's own props/slot at render time. Registered in
+// astro.config.mjs's markdown processor, next to the other remark plugins.
+
+const TREE_NAMES = new Set(['Tree', 'FileTree']);
+
+function textOf(node) {
+  if (!node) return '';
+  if (node.type === 'text' || node.type === 'inlineCode') return node.value;
+  return (node.children ?? []).map(textOf).join('');
+}
+
+function jsxAttr(name, value) {
+  return { type: 'mdxJsxAttribute', name, value };
+}
+
+function listToTreeNodes(list) {
+  return list.children
+    .filter((item) => item.type === 'listItem')
+    .map((item) => {
+      const label = textOf(item.children.find((c) => c.type === 'paragraph')).trim();
+      const nested = item.children.find((c) => c.type === 'list');
+      const isFolder = label.endsWith('/') || Boolean(nested);
+      const name = label.replace(/\/+$/, '');
+      if (!isFolder) {
+        return { type: 'mdxJsxFlowElement', name: 'Tree.File', attributes: [jsxAttr('name', name)], children: [] };
+      }
+      const children = nested ? listToTreeNodes(nested) : [];
+      const attributes = [jsxAttr('name', name)];
+      // "Folders that contain nested items expand by default" - Mintlify's
+      // rule for the list syntax.
+      if (children.length > 0) attributes.push(jsxAttr('defaultOpen', null));
+      return { type: 'mdxJsxFlowElement', name: 'Tree.Folder', attributes, children };
+    });
+}
+
+/**
+ * Mintlify's Markdown-list form of <Tree>/<FileTree>:
+ *
+ *   <FileTree>
+ *
+ *   - docs/
+ *     - index.mdx
+ *   - docs.config.ts
+ *
+ *   </FileTree>
+ *
+ * A trailing slash or nested items make an entry a folder; formatting in a
+ * name (`code`, **bold**) is dropped. Rewritten here into the same
+ * <Tree.Folder>/<Tree.File> elements the component form uses, so Tree.astro
+ * only ever renders one shape.
+ */
+export function remarkMintlifyTreeLists() {
+  return (tree) => {
+    visit(tree, 'mdxJsxFlowElement', (node) => {
+      if (!TREE_NAMES.has(node.name)) return;
+      if (!node.children.some((c) => c.type === 'list')) return;
+      node.children = node.children.flatMap((c) => (c.type === 'list' ? listToTreeNodes(c) : [c]));
+    });
+  };
+}
+
+function dedent(text) {
+  const lines = text.split('\n');
+  const indents = lines.filter((l) => l.trim()).map((l) => l.match(/^[ \t]*/)[0].length);
+  const min = indents.length ? Math.min(...indents) : 0;
+  return lines
+    .map((l) => l.slice(min))
+    .join('\n')
+    .trim();
+}
+
+/**
+ * Mintlify's <Prompt> copies (and sends to Cursor) the prompt's own source
+ * text - Markdown included, e.g. "- Use second-person voice" - not the
+ * rendered HTML's plain text. A component only receives the rendered slot,
+ * so the source is read here, from the file between the element's first
+ * and last child, and passed down as a hidden `_text` prop.
+ */
+export function remarkMintlifyPromptText() {
+  return (tree, file) => {
+    const source = String(file.value ?? '');
+    visit(tree, 'mdxJsxFlowElement', (node) => {
+      if (node.name !== 'Prompt' || node.children.length === 0) return;
+      if (node.attributes.some((a) => a.type === 'mdxJsxAttribute' && a.name === '_text')) return;
+      const start = node.children[0].position?.start?.offset;
+      const end = node.children[node.children.length - 1].position?.end?.offset;
+      if (typeof start !== 'number' || typeof end !== 'number') return;
+      // Back up to the start of the first child's line, so its own
+      // indentation is part of what dedent() measures - but only over
+      // whitespace, never into the <Prompt ...> tag on the same line.
+      const lineStart = source.lastIndexOf('\n', start - 1) + 1;
+      const from = /^[ \t]*$/.test(source.slice(lineStart, start)) ? lineStart : start;
+      node.attributes.push(jsxAttr('_text', dedent(source.slice(from, end))));
+    });
+  };
+}

package/src/lib/mdx-title-anchor-ids.js

@@ -8,7 +8,11 @@ import { visit } from 'unist-util-visit';
 // (Card, Tabs, AccordionGroup, etc. don't). AccordionGroup is deliberately
 // excluded - it has no `title` of its own, just wraps Accordion children
 // that each get their own entry here independently.
-const TITLED_COMPONENT_NAMES = ['Callout', 'Note', 'Info', 'Tip', 'Warning', 'Danger', 'Check', 'Accordion'];
+const TITLED_COMPONENT_NAMES = ['Callout', 'Note', 'Info', 'Tip', 'Warning', 'Danger', 'Check', 'Accordion', 'Update'];
+
+// The attribute each one's anchor text comes from - `title`, except
+// Mintlify's <Update>, whose anchor is its `label`.
+const ANCHOR_ATTRIBUTE = { Update: 'label' };
 
 // Deliberately the same slugify Callout.astro/Accordion.astro themselves
 // fall back to (see their own comments) - kept as a literal duplicate
@@ -67,8 +71,9 @@ export function remarkTitleAnchorIds() {
     const seen = new Map();
     visit(tree, ['mdxJsxFlowElement', 'mdxJsxTextElement'], (node) => {
       if (!node.name || !TITLED_COMPONENT_NAMES.includes(node.name)) return;
+      const attrName = ANCHOR_ATTRIBUTE[node.name] ?? 'title';
       const titleAttr = node.attributes?.find(
-        (attr) => attr.type === 'mdxJsxAttribute' && attr.name === 'title'
+        (attr) => attr.type === 'mdxJsxAttribute' && attr.name === attrName
       );
       if (!titleAttr || typeof titleAttr.value !== 'string') return;
 

package/src/lib/visibility.js

@@ -0,0 +1,29 @@
+// Mintlify's <Visibility for="humans|agents"> in the page source text that
+// writedocs serves to agents - the per-page `.md` route and llms-full.txt,
+// which both hand out a page's raw MDX body rather than its rendered HTML.
+// The rendered site shows `humans` content and hides `agents` content (see
+// Visibility.astro); the text versions do the opposite: `humans` blocks are
+// removed, and `agents` blocks are unwrapped so only their contents remain.
+// A <Visibility> with no `for` counts as `humans`, like the component.
+//
+// Works on source text, not an AST, since that's what these routes serve.
+// Nested <Visibility> blocks aren't supported (Mintlify doesn't document
+// nesting either) - the regex pairs each opening tag with the first
+// closing tag after it.
+
+const VISIBILITY_BLOCK_RE =
+  /<Visibility(?:\s+for\s*=\s*(?:"(humans|agents)"|'(humans|agents)'|\{\s*["'](humans|agents)["']\s*\}))?\s*>([\s\S]*?)<\/Visibility>/g;
+
+function dedent(text) {
+  const lines = text.replace(/^\n+|\s+$/g, '').split('\n');
+  const indents = lines.filter((l) => l.trim()).map((l) => l.match(/^[ \t]*/)[0].length);
+  const min = indents.length ? Math.min(...indents) : 0;
+  return lines.map((l) => l.slice(min)).join('\n');
+}
+
+export function applyVisibilityForAgents(body) {
+  return body.replace(VISIBILITY_BLOCK_RE, (_, dq, sq, expr, inner) => {
+    const audience = dq ?? sq ?? expr ?? 'humans';
+    return audience === 'agents' ? dedent(inner) : '';
+  });
+}

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

@@ -56,6 +56,13 @@ import ParamField from "../components/ParamField.astro";
 import ResponseField from "../components/ResponseField.astro";
 import Columns from "../components/Columns.astro";
 import Tooltip from "../components/Tooltip.astro";
+import Update from "../components/Update.astro";
+import Tile from "../components/Tile.astro";
+import Panel from "../components/Panel.astro";
+import Prompt from "../components/Prompt.astro";
+import View from "../components/View.astro";
+import Visibility from "../components/Visibility.astro";
+import { Tree, FileTree, Color, GitHub } from "../components/compound";
 import ApiPlayground from "../components/ApiPlayground.astro";
 import ApiReferencePanel from "../components/ApiReferencePanel.astro";
 
@@ -438,6 +445,16 @@ const components = {
   ResponseField,
   Columns,
   Tooltip,
+  Update,
+  Tile,
+  Panel,
+  Prompt,
+  View,
+  Visibility,
+  Tree,
+  FileTree,
+  Color,
+  GitHub,
 };
 ---
 
@@ -727,7 +744,12 @@ const components = {
     const tocCol = document.querySelector<HTMLElement>(".wd-toc-col");
     if (!tocCol) return; // no toc column on this page (mode !== 'default') - nothing to dock into
 
-    const panels = Array.from(root.querySelectorAll<HTMLElement>(".wd-example-panel"));
+    // Top-level panels only: Mintlify's <Panel> (Panel.astro) is itself a
+    // .wd-example-panel, and a RequestExample/ResponseExample inside it
+    // moves with it rather than on its own.
+    const panels = Array.from(root.querySelectorAll<HTMLElement>(".wd-example-panel")).filter(
+      (panel) => !panel.parentElement?.closest(".wd-example-panel"),
+    );
     if (panels.length === 0) return;
     if (tocCol.dataset.wdExampleInit) return;
     tocCol.dataset.wdExampleInit = "true";

package/src/pages/[...slug].md.ts

@@ -4,6 +4,7 @@ import path from 'node:path';
 import type { APIRoute } from 'astro';
 import { loadDocsConfig, normalizeEntryId, findAllPages } from '../lib/config';
 import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
+import { applyVisibilityForAgents } from '../lib/visibility.js';
 
 // The raw-Markdown twin of [...slug].astro: every content page is also
 // reachable at the exact same slug with a literal ".md" suffix (e.g.
@@ -73,7 +74,9 @@ export const GET: APIRoute = ({ props }) => {
   // it here means this route needs no separate file read/parse of its
   // own, and always matches exactly what [...slug].astro rendered from
   // (same entry, same collection query).
-  const body = entry.body ?? '';
+  // Mintlify's <Visibility>: this is the agents' view of the page - see
+  // lib/visibility.js.
+  const body = applyVisibilityForAgents(entry.body ?? '');
   const markdown = `# ${entry.data.title}\n\n${body}`;
   return new Response(markdown, {
     headers: { 'Content-Type': 'text/markdown; charset=utf-8' },

package/src/pages/llms-full.txt.ts

@@ -4,6 +4,7 @@ import path from 'node:path';
 import type { APIRoute } from 'astro';
 import { loadDocsConfig, normalizeEntryId, findAllPages } from '../lib/config';
 import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
+import { applyVisibilityForAgents } from '../lib/visibility.js';
 
 // The "everything, concatenated" half of the llms.txt pair - see
 // llms.txt.ts (right next to this file) for the lightweight index half,
@@ -53,7 +54,8 @@ export const GET: APIRoute = async () => {
     .filter((entry) => !entry.data.url)
     .map((entry: DocsEntry) => {
       const slug = normalizeEntryId(entry.id);
-      const body = entry.body ?? '';
+      // Agents' view of <Visibility> blocks, same as the .md route.
+      const body = applyVisibilityForAgents(entry.body ?? '');
       return { slug, title: entry.data.title, body };
     })
     .sort((a, b) => a.slug.localeCompare(b.slug));