@writedocs/generator 0.4.6 → 0.4.8

package/astro.config.mjs

@@ -26,6 +26,7 @@ import { remarkAutoHydrateSnippets } from './src/lib/mdx-auto-hydrate.js';
 import { remarkInjectBuiltinComponents } from './src/lib/mdx-inject-builtins.js';
 import { remarkTitleAnchorIds } from './src/lib/mdx-title-anchor-ids.js';
 import { remarkSubstituteVariables } from './src/lib/mdx-substitute-variables.js';
+import { remarkMintlifyTreeLists, remarkMintlifyPromptText } from './src/lib/mdx-mintlify.js';
 import { writedocsTempDir, writedocsBuildStagingDir } from './src/lib/writedocs-temp-dir.js';
 import { stylesAssetFallback } from './src/lib/styles-asset-integration.js';
 import {
@@ -131,7 +132,12 @@ function collectNoindexIds(rootContentDir) {
   for (const relativeId of findAllPages(rootContentDir)) {
     const file = path.join(rootContentDir, relativeId);
     const { data } = matter(fs.readFileSync(file, 'utf-8'));
-    if (!data?.seo?.noindex) continue;
+    // Top-level `noindex` is Mintlify's spelling, and a Mintlify `hidden`
+    // page is noindexed too - content.config.ts folds both into
+    // `seo.noindex` the same way (an explicit value wins).
+    // A frontmatter `url` page's route only redirects to that link, so it
+    // doesn't belong in the sitemap either.
+    if (!(data?.seo?.noindex ?? data?.noindex ?? data?.hidden === true) && !data?.url) continue;
     const fallbackId = relativeId.replace(/\.mdx?$/i, '').replace(/\/index$/, '');
     ids.add(normalizeEntryId(data.slug ?? fallbackId));
   }
@@ -140,7 +146,7 @@ function collectNoindexIds(rootContentDir) {
   // to the way there is for a hand-written page.
   for (const file of walkMdFiles(generatedDocsDir)) {
     const { data } = matter(fs.readFileSync(file, 'utf-8'));
-    if (data?.seo?.noindex && data.slug) ids.add(normalizeEntryId(data.slug));
+    if ((data?.seo?.noindex ?? data?.noindex ?? data?.hidden === true) && data.slug) ids.add(normalizeEntryId(data.slug));
   }
   return ids;
 }
@@ -192,6 +198,25 @@ function singleSitemapFile() {
 // of only opting into a feature's config surface when it's actually used.
 const redirectsConfig = Object.fromEntries(docsConfig.redirects.map((r) => [r.source, r.destination]));
 
+/** Tailwind only scans the Vite root for class names - this package, not
+ *  the site being built, which is usually somewhere else entirely - so a
+ *  utility class written in a site's own MDX or snippet (Mintlify content
+ *  uses them freely, e.g. className="block dark:hidden") never got
+ *  generated. Appends an @source for the site's content files to
+ *  global.css before Tailwind compiles it. Forward slashes, since
+ *  Tailwind reads the path as a glob. */
+function contentTailwindSource() {
+  const sourceGlob = `${contentDir.split(path.sep).join('/')}/**/*.{md,mdx,jsx,tsx}`;
+  return {
+    name: 'writedocs:content-tailwind-source',
+    enforce: 'pre',
+    transform(code, id) {
+      if (!id.split('?')[0].replace(/\\/g, '/').endsWith('/src/styles/global.css')) return null;
+      return { code: `${code}\n@source ${JSON.stringify(sourceGlob)};\n`, map: null };
+    },
+  };
+}
+
 export default defineConfig({
   ...(siteUrl ? { site: siteUrl } : {}),
   ...(docsConfig.redirects.length ? { redirects: redirectsConfig } : {}),
@@ -339,6 +364,12 @@ export default defineConfig({
       // as raw text first.
       remarkPlugins: [
         remarkMath,
+        // Mintlify's Markdown-list <Tree> and <Prompt> source text - see
+        // lib/mdx-mintlify.js. Before remarkInjectBuiltinComponents, so
+        // the <Tree.Folder>/<Tree.File> elements they add are already in
+        // the tree when it looks for components to import.
+        remarkMintlifyTreeLists,
+        remarkMintlifyPromptText,
         remarkInjectBuiltinComponents,
         // Runs after remarkInjectBuiltinComponents (order doesn't actually
         // matter between them - that plugin only ever prepends an import
@@ -404,7 +435,10 @@ export default defineConfig({
   // working. See src/styles/global.css for the one @import that wires
   // Tailwind's utilities in.
   vite: {
-    plugins: [tailwindcss()],
+    // contentTailwindSource() must come before tailwindcss(): both are
+    // enforce: 'pre' transforms, which Vite runs in array order, and
+    // Tailwind has to see the added @source when it compiles global.css.
+    plugins: [contentTailwindSource(), tailwindcss()],
     resolve: {
       alias: [
         // Lets a page's MDX write `import Foo from '/snippets/foo.mdx'`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.4.6",
+  "version": "0.4.8",
   "description": "Static site generator for docs — a writedocs.json + MDX folder in, a static site out.",
   "type": "module",
   "bin": {

package/src/components/Accordion.astro

@@ -4,6 +4,10 @@ import AppIcon from "./AppIcon.astro";
 interface Props {
   title: string;
   icon?: string;
+  // Mintlify parity: `description` is a muted second line under the title,
+  // `defaultOpen` renders the accordion already expanded.
+  description?: string;
+  defaultOpen?: boolean;
   // Set automatically by remarkTitleAnchorIds (src/lib/mdx-title-anchor-ids.js)
   // for every <Accordion title="..."> it finds in an .mdx file's own JSX,
   // already deduped (-2, -3, ...) against every other Accordion/Callout
@@ -14,7 +18,7 @@ interface Props {
   // title={expr}, or this component used directly from a .astro file).
   _titleId?: string;
 }
-const { title, icon, _titleId } = Astro.props as Props;
+const { title, icon, description, defaultOpen = false, _titleId } = Astro.props as Props;
 // Astro's own heading-id slugging (github-slugger, via the markdown
 // pipeline) never sees this - `title` is a component prop, not a markdown
 // heading, so it gets no id unless we make one ourselves. Same slugify
@@ -28,13 +32,16 @@ function slugify(value: string): string {
 const titleId = _titleId ?? slugify(title);
 ---
 
-<details class="wd-accordion">
+<details class="wd-accordion" open={defaultOpen}>
   <summary>
     <span class="wd-accordion-heading">
       {icon && <AppIcon icon={icon} class="wd-accordion-icon" />}
-      <span class="wd-accordion-title" id={titleId}>
-        {title}
-        <a class="wd-heading-anchor" href={`#${titleId}`} aria-label="Link to this section"> # </a>
+      <span class="wd-accordion-text">
+        <span class="wd-accordion-title" id={titleId}>
+          {title}
+          <a class="wd-heading-anchor" href={`#${titleId}`} aria-label="Link to this section"> # </a>
+        </span>
+        {description && <span class="wd-accordion-description">{description}</span>}
       </span>
     </span>
     {
@@ -128,6 +135,16 @@ const titleId = _titleId ?? slugify(title);
     flex-shrink: 0;
     color: var(--wd-text-muted);
   }
+  .wd-accordion-text {
+    display: flex;
+    flex-direction: column;
+    gap: 0.15rem;
+    min-width: 0;
+  }
+  .wd-accordion-description {
+    font-size: 0.85rem;
+    color: var(--wd-text-muted);
+  }
   .wd-accordion-title {
     font-weight: 700;
     color: var(--wd-text);

package/src/components/AppIcon.astro

@@ -26,6 +26,11 @@ const resolved = icon ? resolveIcon(icon) : null;
 {resolved && (
   resolved.kind === 'iconify' ? (
     <Icon name={resolved.name} class={className} style={style} />
+  ) : resolved.kind === 'image' ? (
+    // Wrapped in the same <span> text icons use, so each caller's own
+    // span.<class> rule (font-size, spacing) sizes it; the image fills
+    // 1em of that (img.wd-icon-img in layout/styles/base.css).
+    <span class={className} style={style}><img src={resolved.src} alt="" class="wd-icon-img" /></span>
   ) : (
     <span class={className} style={style}>{resolved.value}</span>
   )

package/src/components/Callout.astro

@@ -1,5 +1,5 @@
 ---
-// See src/components/{Note,Tip,Warning,Danger,Info}.astro - one thin
+// See src/components/{Note,Tip,Warning,Danger,Info,Check}.astro - one thin
 // wrapper per `type` below, each just `<Callout type="x">` under the
 // hood, so a page can write either `<Callout type="info">` or the
 // shorthand `<Info>` and get an identical result. Both forms take the
@@ -7,7 +7,7 @@
 import AppIcon from "./AppIcon.astro";
 
 interface Props {
-  type?: "note" | "tip" | "warning" | "danger" | "info";
+  type?: "note" | "tip" | "warning" | "danger" | "info" | "check";
   title?: string;
   // Set automatically by remarkCalloutAnchorIds (src/lib/mdx-callout-anchor-ids.js)
   // for every <Callout title="...">/<Note title="...">/etc. it finds in an
@@ -19,8 +19,14 @@ interface Props {
   // dynamic `title={expr}`, or this component used directly from a .astro
   // file rather than through MDX).
   _titleId?: string;
+  // Mintlify's custom callout: `icon` replaces the type's own icon (any
+  // icon string AppIcon accepts), `color` replaces its accent color - the
+  // border, tint, icon and title all derive from that one value.
+  icon?: string;
+  color?: string;
 }
-const { type = "note", title, _titleId } = Astro.props as Props;
+const { type = "note", title, _titleId, icon, color } = Astro.props as Props;
+const accentStyle = color ? `--wd-callout-accent: ${color}` : undefined;
 // FontAwesome Solid (fa6-solid, already an installed @iconify-json/*
 // collection - see astro.config.mjs's own comment on icon() needing no
 // allowlist) rather than a literal emoji, so every callout gets a real,
@@ -31,6 +37,7 @@ const icons: Record<string, string> = {
   tip: "fa6-solid:lightbulb",
   warning: "fa6-solid:triangle-exclamation",
   danger: "fa6-solid:circle-xmark",
+  check: "fa6-solid:circle-check",
 };
 // Astro's own heading-id slugging (github-slugger, via the markdown
 // pipeline) never sees this - `title` is a component prop, not a
@@ -44,8 +51,8 @@ function slugify(value: string): string {
 const titleId = title ? (_titleId ?? slugify(title)) : undefined;
 ---
 
-<div class:list={["wd-callout", `wd-callout-${type}`, { "wd-callout-titled": Boolean(title) }]}>
-  <AppIcon icon={icons[type]} class="wd-callout-icon" />
+<div class:list={["wd-callout", `wd-callout-${type}`, { "wd-callout-titled": Boolean(title) }]} style={accentStyle}>
+  <AppIcon icon={icon ?? icons[type]} class="wd-callout-icon" />
   <div class="wd-callout-content">
     {
       title && (
@@ -165,4 +172,7 @@ const titleId = title ? (_titleId ?? slugify(title)) : undefined;
   .wd-callout-danger {
     --wd-callout-accent: #dc2626;
   }
+  .wd-callout-check {
+    --wd-callout-accent: #059669;
+  }
 </style>

package/src/components/Card.astro

@@ -26,27 +26,40 @@ interface Props {
   // generic component over a handful of literal hex values).
   method?: string;
   href?: string;
+  // Mintlify's Card props: `color` tints the icon, `horizontal` puts the
+  // icon beside the text instead of above it, `cta` adds a call-to-action
+  // line at the bottom, and `arrow` marks a linked card with an arrow in
+  // its corner.
+  color?: string;
+  horizontal?: boolean;
+  cta?: string;
+  arrow?: boolean;
 }
-const { title, icon, img, method, href } = Astro.props as Props;
+const { title, icon, img, method, href, color, horizontal = false, cta, arrow = false } = Astro.props as Props;
+const iconStyle = color ? `color: ${color}` : undefined;
 const Tag = href ? 'a' : 'div';
 const KNOWN_METHODS = ['get', 'post', 'put', 'patch', 'delete'];
 const methodLower = method?.toLowerCase();
 const methodClass = methodLower && KNOWN_METHODS.includes(methodLower) ? methodLower : 'other';
 ---
-<Tag class="wd-card" href={href}>
+<Tag class:list={['wd-card', { 'wd-card-horizontal': horizontal, 'wd-card-has-arrow': arrow && href }]} href={href}>
   {img && <img src={img} alt="" class="wd-card-image" />}
-  {!img && <AppIcon icon={icon} class="wd-card-icon" />}
-  <div class="wd-card-title-row">
-    <h3 class="wd-card-title">{title}</h3>
-    {
-      method && (
-        <span class:list={['wd-card-method', `wd-card-method-${methodClass}`]}>
-          {method.toUpperCase()}
-        </span>
-      )
-    }
+  {!img && <AppIcon icon={icon} class="wd-card-icon" style={iconStyle} />}
+  <div class="wd-card-text">
+    <div class="wd-card-title-row">
+      <h3 class="wd-card-title">{title}</h3>
+      {
+        method && (
+          <span class:list={['wd-card-method', `wd-card-method-${methodClass}`]}>
+            {method.toUpperCase()}
+          </span>
+        )
+      }
+    </div>
+    <div class="wd-card-body"><slot /></div>
+    {cta && <span class="wd-card-cta">{cta} <span aria-hidden="true">&rarr;</span></span>}
   </div>
-  <div class="wd-card-body"><slot /></div>
+  {arrow && href && <span class="wd-card-arrow" aria-hidden="true">&#8599;</span>}
 </Tag>
 <style>
   .wd-card {
@@ -133,4 +146,42 @@ const methodClass = methodLower && KNOWN_METHODS.includes(methodLower) ? methodL
   .wd-card-body :global(p) {
     margin: 0;
   }
+  /* Icon in its own column beside the title/body, both vertically
+     centered - Mintlify's compact horizontal card. */
+  .wd-card-horizontal {
+    display: flex;
+    align-items: center;
+    gap: 0.9rem;
+  }
+  .wd-card-horizontal .wd-card-title-row {
+    margin-top: 0;
+  }
+  .wd-card-text {
+    min-width: 0;
+    flex: 1;
+  }
+  .wd-card-cta {
+    display: inline-block;
+    margin-top: 0.7rem;
+    font-size: 0.85rem;
+    font-weight: 600;
+    color: var(--wd-primary);
+  }
+  /* Only a card that shows the arrow becomes a positioning context -
+     setting it on every card changed how existing cards' text was
+     antialiased, for no layout reason. */
+  .wd-card-has-arrow {
+    position: relative;
+  }
+  .wd-card-arrow {
+    position: absolute;
+    top: 0.8rem;
+    right: 0.9rem;
+    color: var(--wd-text-muted);
+    font-size: 0.95rem;
+    line-height: 1;
+  }
+  a.wd-card:hover .wd-card-arrow {
+    color: var(--wd-primary);
+  }
 </style>

package/src/components/Check.astro

@@ -0,0 +1,13 @@
+---
+// Shorthand for <Callout type="check"> - Mintlify's <Check> ("this worked",
+// "you're done"). See Callout.astro's own comment.
+import Callout from './Callout.astro';
+interface Props {
+  title?: string;
+  // See Callout.astro's own comment - set automatically by
+  // remarkCalloutAnchorIds, not meant to be passed by hand.
+  _titleId?: string;
+}
+const { title, _titleId } = Astro.props as Props;
+---
+<Callout type="check" title={title} _titleId={_titleId}><slot /></Callout>

package/src/components/Color.astro

@@ -0,0 +1,61 @@
+---
+// Mintlify's <Color> - a palette of <Color.Item> swatches. `variant`:
+//   compact (default) - one grid of swatches.
+//   table             - <Color.Row title="..."> rows, each a titled line of
+//                       swatches.
+// Color.Row/Color.Item are ColorRow.astro/ColorItem.astro, attached as
+// properties in components/compound.ts so the dotted names resolve in MDX.
+interface Props {
+  variant?: 'compact' | 'table';
+}
+const { variant = 'compact' } = Astro.props as Props;
+---
+<div class:list={['wd-color', `wd-color-${variant}`]}><slot /></div>
+<script>
+  // Click (or Enter/Space) on a swatch copies the value currently shown -
+  // for a light/dark pair, the one matching the site's theme right now.
+  function initColorCopy(root: ParentNode) {
+    root.querySelectorAll<HTMLElement>('.wd-color-item[data-light]').forEach((item) => {
+      if (item.dataset.wdInit) return;
+      item.dataset.wdInit = 'true';
+      const copy = async () => {
+        const dark = document.documentElement.dataset.theme === 'dark';
+        const value = (dark ? item.dataset.dark : item.dataset.light) ?? '';
+        const label = item.querySelector<HTMLElement>('.wd-color-copied');
+        try {
+          await navigator.clipboard.writeText(value);
+          if (label) label.textContent = 'Copied';
+        } catch {
+          if (label) label.textContent = 'Copy failed';
+        }
+        setTimeout(() => label && (label.textContent = ''), 1200);
+      };
+      item.addEventListener('click', copy);
+      item.addEventListener('keydown', (e) => {
+        if (e.key === 'Enter' || e.key === ' ') {
+          e.preventDefault();
+          copy();
+        }
+      });
+    });
+  }
+  initColorCopy(document);
+  document.addEventListener('astro:page-load', () => initColorCopy(document));
+</script>
+<style>
+  .wd-color {
+    margin: 1.25rem 0;
+  }
+  .wd-color-compact {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(8.5rem, 1fr));
+    gap: 1rem;
+  }
+  .wd-color-table {
+    display: flex;
+    flex-direction: column;
+    border: 1px solid var(--wd-border);
+    border-radius: 0.6rem;
+    overflow: hidden;
+  }
+</style>

package/src/components/ColorItem.astro

@@ -0,0 +1,93 @@
+---
+// Mintlify's <Color.Item name="..." value="..."> - one swatch. `value` is
+// any CSS color, or { light, dark } for a theme-aware pair: the swatch and
+// the value text switch with the site's theme toggle ([data-theme] on
+// <html>), via the two custom properties below. Click copies the value
+// (Color.astro's script).
+interface Props {
+  name?: string;
+  value?: string | { light: string; dark: string };
+}
+const { name, value } = Astro.props as Props;
+const light = typeof value === 'string' ? value : value?.light;
+const dark = typeof value === 'string' ? value : value?.dark;
+const themed = typeof value === 'object' && value !== null && light !== dark;
+const style = light ? `--wd-swatch-light: ${light}; --wd-swatch-dark: ${dark ?? light}` : undefined;
+---
+<div
+  class="wd-color-item"
+  data-light={light}
+  data-dark={dark}
+  role={light ? 'button' : undefined}
+  tabindex={light ? 0 : undefined}
+  title={light ? 'Copy value' : undefined}
+  style={style}
+>
+  <div class="wd-color-swatch"></div>
+  <div class="wd-color-name">{name}</div>
+  {light && (
+    <div class="wd-color-value">
+      {themed ? (
+        <>
+          <span class="wd-color-value-light">{light}</span>
+          <span class="wd-color-value-dark">{dark}</span>
+        </>
+      ) : (
+        light
+      )}
+      <span class="wd-color-copied" aria-live="polite"></span>
+    </div>
+  )}
+</div>
+<style>
+  .wd-color-item {
+    min-width: 0;
+  }
+  .wd-color-item[role='button'] {
+    cursor: pointer;
+  }
+  /* A checkerboard under the swatch, so a translucent color (rgba, hsla)
+     reads as translucent rather than as a lighter solid. */
+  .wd-color-swatch {
+    height: 3.5rem;
+    border: 1px solid var(--wd-border);
+    border-radius: 0.5rem;
+    background:
+      linear-gradient(var(--wd-swatch-light, transparent), var(--wd-swatch-light, transparent)),
+      repeating-conic-gradient(var(--wd-surface) 0% 25%, var(--wd-background) 0% 50%) 0 0 / 12px 12px;
+  }
+  :global([data-theme='dark']) .wd-color-swatch {
+    background:
+      linear-gradient(var(--wd-swatch-dark, transparent), var(--wd-swatch-dark, transparent)),
+      repeating-conic-gradient(var(--wd-surface) 0% 25%, var(--wd-background) 0% 50%) 0 0 / 12px 12px;
+  }
+  .wd-color-item[role='button']:hover .wd-color-swatch,
+  .wd-color-item[role='button']:focus-visible .wd-color-swatch {
+    border-color: var(--wd-primary);
+  }
+  .wd-color-name {
+    margin-top: 0.4rem;
+    font-size: 0.85rem;
+    font-weight: 600;
+    overflow-wrap: anywhere;
+  }
+  .wd-color-value {
+    font-family: monospace;
+    font-size: 0.75rem;
+    color: var(--wd-text-muted);
+    overflow-wrap: anywhere;
+  }
+  .wd-color-value-dark {
+    display: none;
+  }
+  :global([data-theme='dark']) .wd-color-value-light {
+    display: none;
+  }
+  :global([data-theme='dark']) .wd-color-value-dark {
+    display: inline;
+  }
+  .wd-color-copied {
+    margin-left: 0.35rem;
+    color: var(--wd-primary);
+  }
+</style>

package/src/components/ColorRow.astro

@@ -0,0 +1,39 @@
+---
+// Mintlify's <Color.Row title="..."> - one titled row inside
+// <Color variant="table">. `title` takes inline Markdown.
+import { inlineMarkdown } from '../lib/inline-markdown.js';
+interface Props {
+  title?: string;
+}
+const { title } = Astro.props as Props;
+---
+<div class="wd-color-row">
+  <div class="wd-color-row-title" set:html={inlineMarkdown(title ?? '')} />
+  <div class="wd-color-row-items"><slot /></div>
+</div>
+<style>
+  .wd-color-row {
+    display: grid;
+    grid-template-columns: 9rem minmax(0, 1fr);
+    gap: 1rem;
+    align-items: center;
+    padding: 1rem;
+  }
+  .wd-color-row + .wd-color-row {
+    border-top: 1px solid var(--wd-border);
+  }
+  .wd-color-row-title {
+    font-weight: 600;
+    font-size: 0.9rem;
+  }
+  .wd-color-row-items {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(7.5rem, 1fr));
+    gap: 1rem;
+  }
+  @media (max-width: 640px) {
+    .wd-color-row {
+      grid-template-columns: minmax(0, 1fr);
+    }
+  }
+</style>

package/src/components/Columns.astro

@@ -0,0 +1,11 @@
+---
+// Mintlify's <Columns cols={n}> - the grid Mintlify now uses around Cards
+// (its docs moved from <CardGroup> to this). Same grid as CardGroup.astro,
+// which already lays out any children, not only Cards.
+import CardGroup from './CardGroup.astro';
+interface Props {
+  cols?: number;
+}
+const { cols } = Astro.props as Props;
+---
+<CardGroup cols={cols}><slot /></CardGroup>

package/src/components/Frame.astro

@@ -12,13 +12,17 @@
 // component's name collides with frontmatter's own `mode: "frame"`
 // page-rendering option (BaseLayout.astro) - that's an unrelated,
 // page-level concept keyed off a plain string, not a JSX component.
+// `hint` is Mintlify's: a short line shown above the framed content, as
+// opposed to `caption` below it.
 interface Props {
   caption?: string;
+  hint?: string;
 }
-const { caption } = Astro.props as Props;
+const { caption, hint } = Astro.props as Props;
 ---
 
 <figure class="wd-frame">
+  {hint && <p class="wd-frame-hint">{hint}</p>}
   <div class="wd-frame-content">
     <slot />
   </div>
@@ -93,6 +97,11 @@ const { caption } = Astro.props as Props;
   .wd-frame-content :global(p) {
     display: contents;
   }
+  .wd-frame-hint {
+    margin: 0.1rem 0.25rem 0.5rem;
+    color: var(--wd-text-muted);
+    font-size: 0.8rem;
+  }
   .wd-frame-caption {
     margin: 0.6rem 0 0;
     text-align: center;