@writedocs/generator 0.4.6 → 0.4.7

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

@@ -34,6 +34,11 @@ const BUILTIN_COMPONENT_NAMES = [
   'Icon',
   'RequestExample',
   'ResponseExample',
+  'Check',
+  'ParamField',
+  'ResponseField',
+  'Columns',
+  'Tooltip',
 ];
 
 const PACKAGE_SPECIFIER = 'writedocs/components';

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

@@ -8,7 +8,7 @@ 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'];
 
 // Deliberately the same slugify Callout.astro/Accordion.astro themselves
 // fall back to (see their own comments) - kept as a literal duplicate

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/pages/[...slug].astro

@@ -51,6 +51,11 @@ 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 ApiPlayground from "../components/ApiPlayground.astro";
 import ApiReferencePanel from "../components/ApiReferencePanel.astro";
 
@@ -156,6 +161,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 +198,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 +298,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 +311,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 +334,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 +357,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 +433,11 @@ const components = {
   Icon,
   RequestExample,
   ResponseExample,
+  Check,
+  ParamField,
+  ResponseField,
+  Columns,
+  Tooltip,
 };
 ---
 
@@ -430,13 +467,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 +534,7 @@ const components = {
             </a>
           )}
         </nav>
+        )}
       </article>
     )
   }
@@ -777,6 +827,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 +1059,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

@@ -52,6 +52,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 },

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

@@ -49,6 +49,8 @@ export const GET: APIRoute = async () => {
     // Same noindex exclusion llms.txt.ts applies to its own listing -
     // see that file's comment.
     .filter((entry) => !entry.data.seo?.noindex)
+    // Same `url` exclusion as llms.txt.ts - a redirect, not a page.
+    .filter((entry) => !entry.data.url)
     .map((entry: DocsEntry) => {
       const slug = normalizeEntryId(entry.id);
       const body = entry.body ?? '';

package/src/pages/llms.txt.ts

@@ -85,6 +85,9 @@ export const GET: APIRoute = async () => {
     // same reason: llms.txt exists to help external tools discover
     // pages, exactly what `noindex` asked not to happen.
     .filter((entry) => !entry.data.seo?.noindex)
+    // A frontmatter `url` page (Mintlify's external link) has no content -
+    // its own URL only redirects to the link.
+    .filter((entry) => !entry.data.url)
     .map((entry: DocsEntry) => {
       const slug = normalizeEntryId(entry.id);
       // Same URL Astro's own router resolves this entry to - see

package/src/styles/global.css

@@ -16,3 +16,13 @@
    classes available with zero effect on existing unstyled elements. */
 @import "tailwindcss/theme.css";
 @import "tailwindcss/utilities.css";
+
+/* Tailwind's `dark:` variant follows the site's own theme toggle
+   ([data-theme="dark"] on <html>, set by BaseLayout.astro), not the OS
+   setting it defaults to - otherwise Mintlify-style light/dark image
+   pairs (className="block dark:hidden" / "hidden dark:block") show the
+   wrong one whenever the reader's toggle and their OS disagree. The
+   site's content directory is added as a Tailwind source at build time
+   by astro.config.mjs's contentTailwindSource() plugin, since it lives
+   outside this package where Tailwind looks by default. */
+@custom-variant dark (&:where([data-theme="dark"], [data-theme="dark"] *));