@writedocs/generator 0.4.6 → 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

@@ -34,6 +34,21 @@ const BUILTIN_COMPONENT_NAMES = [
   'Icon',
   'RequestExample',
   'ResponseExample',
+  'Check',
+  'ParamField',
+  'ResponseField',
+  'Columns',
+  'Tooltip',
+  'Update',
+  'Tile',
+  'Panel',
+  'Prompt',
+  'View',
+  'Visibility',
+  'Tree',
+  'FileTree',
+  'Color',
+  'GitHub',
 ];
 
 const PACKAGE_SPECIFIER = 'writedocs/components';
@@ -72,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', '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/shiki-code-block.js

@@ -21,33 +21,124 @@
 // at all, so this only ever touches genuine ```-fenced MDX content and
 // never collides with the API playground's own bespoke copy buttons.
 
-const META_TITLE_RE = /title\s*=\s*(["'])((?:(?!\1).)*)\1/;
+import { iconSvg } from './config.ts';
 
-function parseMeta(raw) {
-  return {
-    title: raw.match(META_TITLE_RE)?.[2] ?? null,
-    wrap: /\bwrap\b/.test(raw),
-    lines: /\b(?:lines|showLineNumbers)\b/.test(raw),
-    expandable: /\bexpandable\b/.test(raw),
+// The fence's info string after the language, split into tokens: a
+// `key=value` option (value quoted, in braces, or bare), a bare `{1,3-5}`
+// range, a `/word/` pattern, or any other bare word.
+const META_TOKEN_RE = /([A-Za-z][\w-]*)=(?:"([^"]*)"|'([^']*)'|\{([^}]*)\}|(\S+))|\{([^}]*)\}|(\/(?:\\.|[^/\s])+\/)(?=\s|$)|(\S+)/g;
+
+// Bare words that are options, not title text. Case-sensitive on purpose:
+// Mintlify's own docs write ```js Wrap example wrap, where the capitalized
+// "Wrap" is part of the title and only the trailing "wrap" is the flag.
+const META_FLAGS = new Set(['wrap', 'lines', 'showLineNumbers', 'expandable', 'nocopy', 'twoslash']);
+
+function parseRanges(value) {
+  return value
+    .split(',')
+    .map((part) => part.trim())
+    .filter(Boolean)
+    .flatMap((part) => {
+      const [start, end] = part.split('-').map((n) => Number.parseInt(n, 10));
+      if (Number.isNaN(start)) return [];
+      if (end === undefined || Number.isNaN(end)) return [start];
+      return Array.from({ length: end - start + 1 }, (_, i) => start + i);
+    });
+}
+
+/** Parses a fence's info string in both syntaxes writedocs accepts:
+ *  its own (```js title="a.js" {1,3} wrap) and Mintlify's
+ *  (```js a.js highlight={1,3} focus={2} icon="js" nocopy wrap) - the
+ *  Mintlify title is the run of plain words right after the language,
+ *  before the first option. `title="..."` wins over an inline title.
+ *
+ *  `shikiMeta` is what the stock @shikijs/transformers meta transformers
+ *  get to see instead of the raw string (see preprocess below): only the
+ *  highlight range and the /word/ patterns. Read raw, those transformers
+ *  would take focus={2} as a highlight range (they grab the first {...}
+ *  anywhere) and a / inside a title or path as a word to highlight. */
+export function parseMeta(raw) {
+  const meta = {
+    title: null,
+    icon: null,
+    wrap: false,
+    lines: false,
+    expandable: false,
+    nocopy: false,
+    twoslash: false,
+    highlight: [],
+    focus: [],
+    words: [],
   };
+  const titleWords = [];
+  let sawOption = false;
+  for (const m of raw.matchAll(META_TOKEN_RE)) {
+    const [, key, dq, sq, braced, bare, bareRange, word, other] = m;
+    if (key !== undefined) {
+      sawOption = true;
+      const value = dq ?? sq ?? braced ?? bare ?? '';
+      if (key === 'title') meta.title = value;
+      else if (key === 'icon') meta.icon = value;
+      else if (key === 'highlight') meta.highlight.push(...parseRanges(value));
+      else if (key === 'focus') meta.focus.push(...parseRanges(value));
+      // Mintlify's `nocopy="false"` (explicitly keep the copy button).
+      else if (META_FLAGS.has(key)) meta[key === 'showLineNumbers' ? 'lines' : key] = value !== 'false';
+      continue;
+    }
+    if (bareRange !== undefined) {
+      sawOption = true;
+      meta.highlight.push(...parseRanges(bareRange));
+      continue;
+    }
+    if (word !== undefined) {
+      sawOption = true;
+      meta.words.push(word);
+      continue;
+    }
+    if (META_FLAGS.has(other)) {
+      sawOption = true;
+      meta[other === 'showLineNumbers' ? 'lines' : other] = true;
+      continue;
+    }
+    if (!sawOption) titleWords.push(other);
+  }
+  if (meta.title === null && titleWords.length > 0) meta.title = titleWords.join(' ');
+  const shikiParts = [];
+  if (meta.highlight.length > 0) shikiParts.push(`{${meta.highlight.join(',')}}`);
+  shikiParts.push(...meta.words);
+  meta.shikiMeta = shikiParts.join(' ');
+  return meta;
 }
 
 export function codeBlockTransformer() {
   return {
     name: 'writedocs:code-block',
-    // Runs once per block, before `root` - stashes the parsed meta
-    // flags on `this` (the shared per-block transformer context; see
-    // @shikijs/core's tokensToHast, which calls both `pre` and `root`
-    // with the same `context` object for a given block, but a *fresh*
-    // one for each block) so `root` below doesn't have to re-parse it.
+    // preprocess runs before every other hook of every transformer (see
+    // @shikijs/core's codeToTokens), so this is where the raw info string
+    // is parsed once and swapped for the cleaned-up `shikiMeta` the stock
+    // meta-highlight transformers read - see parseMeta() above. The full
+    // parse is kept on the same options object for the hooks below.
+    preprocess(code, options) {
+      if (options.meta) {
+        options.meta.__wdMeta = parseMeta(options.meta.__raw ?? '');
+        options.meta.__raw = options.meta.__wdMeta.shikiMeta;
+      }
+      return code;
+    },
+    line(node, lineNumber) {
+      if (this.options.meta?.__wdMeta?.focus.includes(lineNumber)) this.addClassToHast(node, 'focused');
+      return node;
+    },
+    // Same classes transformerNotationFocus (`// [!code focus]`) adds, so
+    // `focus={...}` reuses [...slug].astro's existing dimming CSS.
     pre(node) {
-      this.wdMeta = parseMeta(this.options.meta?.__raw ?? '');
+      if (this.options.meta?.__wdMeta?.focus.length) this.addClassToHast(node, 'has-focused');
       return node;
     },
     root(hast) {
       const pre = hast.children.find((child) => child.type === 'element' && child.tagName === 'pre');
       if (!pre) return hast;
-      const meta = this.wdMeta ?? parseMeta(this.options.meta?.__raw ?? '');
+      const meta = this.options.meta?.__wdMeta ?? parseMeta(this.options.meta?.__raw ?? '');
 
       const wrapperClass = ['wd-code-block'];
       if (meta.wrap) wrapperClass.push('wd-code-wrap');
@@ -56,25 +147,48 @@ export function codeBlockTransformer() {
 
       const children = [];
       if (meta.title) {
+        const titleChildren = [];
+        // Drawn as a CSS mask over currentColor, so the icon takes the
+        // title bar's own text color in both themes. An icon string that
+        // isn't an installed icon (emoji, unknown name) is skipped rather
+        // than failing the build.
+        const svg = meta.icon ? iconSvg(meta.icon) : null;
+        if (svg) {
+          titleChildren.push({
+            type: 'element',
+            tagName: 'span',
+            properties: {
+              class: 'wd-code-title-icon',
+              'aria-hidden': 'true',
+              style: `--wd-code-icon: url("data:image/svg+xml,${encodeURIComponent(svg)}")`,
+            },
+            children: [],
+          });
+        }
+        titleChildren.push({ type: 'text', value: meta.title });
         children.push({
           type: 'element',
           tagName: 'div',
           properties: { class: 'wd-code-title' },
-          children: [{ type: 'text', value: meta.title }],
+          children: titleChildren,
         });
       }
       children.push(pre);
-      children.push({
-        type: 'element',
-        tagName: 'button',
-        properties: {
-          type: 'button',
-          class: 'wd-code-copy-btn',
-          'data-role': 'copy-code',
-          'aria-label': 'Copy code',
-        },
-        children: [{ type: 'text', value: '⧉' }],
-      });
+      // Mintlify's `nocopy` - for content where copying makes no sense
+      // (ASCII diagrams, sample output).
+      if (!meta.nocopy) {
+        children.push({
+          type: 'element',
+          tagName: 'button',
+          properties: {
+            type: 'button',
+            class: 'wd-code-copy-btn',
+            'data-role': 'copy-code',
+            'aria-label': 'Copy code',
+          },
+          children: [{ type: 'text', value: '⧉' }],
+        });
+      }
       if (meta.expandable) {
         children.push({
           type: 'element',

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

@@ -51,6 +51,18 @@ import Badge from "../components/Badge.astro";
 import Icon from "../components/Icon.astro";
 import RequestExample from "../components/RequestExample.astro";
 import ResponseExample from "../components/ResponseExample.astro";
+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 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";
 
@@ -156,6 +168,15 @@ export async function getStaticPaths() {
 
   const pageRoutes = sections.flatMap((section, sectionIndex) => {
     const flatNav = flattenNav(section.pages);
+    // Prev/next skip pages that aren't in the sidebar (frontmatter
+    // `hidden`) or aren't pages at all (frontmatter `url`, an external
+    // link) - the reader should land on the next page they could also
+    // have clicked in the sidebar. Inlined for the same reason as the
+    // error branch below.
+    const isPaginationStop = (slug: string) => {
+      const data = entryByFileId.get(slug)?.data;
+      return Boolean(data) && !data!.hidden && !data!.url;
+    };
     return flatNav.map((navEntry, i) => {
       const entry = entryByFileId.get(navEntry.slug);
       if (!entry) {
@@ -184,9 +205,17 @@ export async function getStaticPaths() {
         );
       }
       claimedFileIds.add(navEntry.slug);
-      const prev = i > 0 ? flatNav[i - 1] : null;
-      const next = i < flatNav.length - 1 ? flatNav[i + 1] : null;
+      const prev = flatNav.slice(0, i).findLast((e) => isPaginationStop(e.slug)) ?? null;
+      const next = flatNav.slice(i + 1).find((e) => isPaginationStop(e.slug)) ?? null;
       const urlSlug = normalizeEntryId(entry.id);
+      // A frontmatter `url` page (Mintlify's external link) exists only
+      // to put that link in the sidebar - its own URL redirects there.
+      if (entry.data.url) {
+        return {
+          params: { slug: urlSlug === "index" ? undefined : urlSlug },
+          props: { redirectTo: entry.data.url },
+        };
+      }
       return {
         params: { slug: urlSlug === "index" ? undefined : urlSlug },
         props: { entry, prev, next, sectionIndex },
@@ -276,6 +305,9 @@ const entries: DocsEntry[] = [...pagesEntries, ...generatedDocsEntries];
 // themselves so hrefForSlug can resolve a writedocs.json file-id reference to
 // wherever that page actually got routed.
 const titleByFileId = new Map<string, string>();
+// Navigation labels (sidebar, topbar dropdowns): a page's `sidebarTitle`
+// when it has one - Mintlify's short nav label - else its `title`.
+const navTitleByFileId = new Map<string, string>();
 const entryByFileId = new Map<string, DocsEntry>();
 // The HTTP method badge NavTree.astro shows next to an API operation
 // page in the sidebar - read straight off the page's own `openapi:
@@ -286,13 +318,19 @@ const methodByFileId = new Map<string, string>();
 for (const e of entries) {
   const fileId = fileIdForEntry(contentDir, packageRoot, e);
   titleByFileId.set(fileId, e.data.title);
+  navTitleByFileId.set(fileId, e.data.sidebarTitle ?? e.data.title);
   entryByFileId.set(fileId, e);
-  if (e.data.openapi) {
+  // `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 titleForSlug = (slug: string) => titleByFileId.get(slug) ?? slug;
+const navTitleForSlug = (slug: string) => navTitleByFileId.get(slug) ?? slug;
 const methodForSlug = (slug: string) => methodByFileId.get(slug) ?? null;
+// Frontmatter that changes how a page appears in navigation (hidden, url,
+// icon, tag, deprecated) - see buildNavTree() in lib/config.ts.
+const navMetaForSlug = (slug: string) => entryByFileId.get(slug)?.data;
 const hrefForSlug = (slug: string) => {
   const raw = entryByFileId.get(slug)?.id ?? slug;
   const effective = normalizeEntryId(raw);
@@ -303,7 +341,7 @@ const hrefForSlug = (slug: string) => {
 // and what every "is this the active page" comparison below needs, since
 // navTree/globalDropdowns are built from writedocs.json's file-id space.
 const currentFileId = fileIdForEntry(contentDir, packageRoot, entry);
-const navTree = buildNavTree(activeSection.pages, titleForSlug, methodForSlug);
+const navTree = buildNavTree(activeSection.pages, navTitleForSlug, methodForSlug, navMetaForSlug);
 // The ancestor sidebar-group trail above the auto <h1> (Breadcrumbs.astro)
 // - empty for a page sitting at the top level of its Section with no
 // enclosing group, in which case [...slug].astro below skips rendering
@@ -326,8 +364,9 @@ const selectors = buildSelectors(activeSection.path, hrefForSlug, activePagePosi
 const globalDropdowns = buildGlobalDropdowns(
   resolveGlobalDropdowns(config.navigation),
   currentFileId,
-  titleForSlug,
+  navTitleForSlug,
   hrefForSlug,
+  navMetaForSlug,
 );
 
 // Meta tags: this page's own frontmatter `seo` overrides writedocs.json's
@@ -401,6 +440,21 @@ const components = {
   Icon,
   RequestExample,
   ResponseExample,
+  Check,
+  ParamField,
+  ResponseField,
+  Columns,
+  Tooltip,
+  Update,
+  Tile,
+  Panel,
+  Prompt,
+  View,
+  Visibility,
+  Tree,
+  FileTree,
+  Color,
+  GitHub,
 };
 ---
 
@@ -430,13 +484,25 @@ const components = {
       <article class={`wd-article ${pageMode === "wide" ? "wd-article-wide" : ""}`} data-pagefind-body>
         {breadcrumbs.length > 0 && <Breadcrumbs items={breadcrumbs} />}
         <div class="wd-article-header">
-          <h1 data-pagefind-meta="title">{entry.data.title}</h1>
+          {
+            // Frontmatter `deprecated` puts a label beside the <h1>, not in
+            // it - the <h1>'s text is the search index's page title.
+            entry.data.deprecated ? (
+              <div class="wd-article-title">
+                <h1 data-pagefind-meta="title">{entry.data.title}</h1>
+                <span class="wd-deprecated-badge">Deprecated</span>
+              </div>
+            ) : (
+              <h1 data-pagefind-meta="title">{entry.data.title}</h1>
+            )
+          }
           {showCopyPageMenu && (
             <CopyPageMenu currentPath={currentPath} siteUrl={siteUrl} contextMenu={config.contextMenu!} />
           )}
         </div>
         <Content components={components} />
         {entry.data.openapi && <ApiPlayground operation={entry.data.openapi} contentDir={contentDir} />}
+        {!entry.data.hideFooterPagination && (
         <nav class="wd-prevnext" data-pagefind-ignore>
           {prev && (
             <a class="wd-prevnext-card wd-prevnext-prev" href={hrefForSlug(prev.slug)}>
@@ -485,6 +551,7 @@ const components = {
             </a>
           )}
         </nav>
+        )}
       </article>
     )
   }
@@ -677,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";
@@ -777,6 +849,24 @@ const components = {
   .wd-article-header h1 {
     margin: 0;
   }
+  /* Frontmatter `deprecated: true` (Mintlify's) - same amber as the
+     sidebar's own deprecated tag (NavTree.astro) and Parameter's
+     deprecated badge. */
+  .wd-article-title {
+    display: flex;
+    align-items: center;
+    flex-wrap: wrap;
+    gap: 0.6rem;
+  }
+  .wd-deprecated-badge {
+    display: inline-block;
+    padding: 0.15rem 0.55rem;
+    border-radius: 999px;
+    font-size: 0.8rem;
+    font-weight: 700;
+    color: #d97706;
+    background: color-mix(in srgb, #d97706 15%, transparent);
+  }
   .wd-prevnext {
     display: flex;
     justify-content: space-between;
@@ -991,6 +1081,19 @@ const components = {
     background: var(--wd-surface);
     border-bottom: 1px solid var(--wd-border);
   }
+  /* A fence's `icon="..."` (shiki-code-block.js) - the icon's own SVG
+     arrives as a data URL in --wd-code-icon and is used as a mask, so it
+     paints in the title's text color instead of the SVG's own fill. */
+  .wd-code-title-icon {
+    display: inline-block;
+    width: 1em;
+    height: 1em;
+    margin-right: 0.45rem;
+    vertical-align: -0.125em;
+    background: currentColor;
+    -webkit-mask: var(--wd-code-icon) center / contain no-repeat;
+    mask: var(--wd-code-icon) center / contain no-repeat;
+  }
   .wd-code-copy-btn {
     position: absolute;
     top: 0.6rem;

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.
@@ -52,6 +53,9 @@ export async function getStaticPaths() {
     // as an LLM-facing "view this page as text" export, so they're left
     // out of this route entirely rather than serving something misleading.
     .filter((entry) => !entry.data.openapi)
+    // A frontmatter `url` page's HTML route is a redirect to that link -
+    // there's no page content to serve as Markdown.
+    .filter((entry) => !entry.data.url)
     .map((entry) => ({
       params: { slug: normalizeEntryId(entry.id) },
       props: { entry },
@@ -70,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' },