@writedocs/generator 0.4.7 → 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 {
@@ -363,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@writedocs/generator",
-  "version": "0.4.7",
+  "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/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/GitHubRepo.astro

@@ -0,0 +1,156 @@
+---
+// Mintlify's <GitHub.Repo repo="owner/name" variant="inset|flat"> - a card
+// linking to a public GitHub repository. Attached as GitHub.Repo in
+// components/compound.ts. `repo` is an "owner/name" slug or a full
+// github.com URL.
+//
+// The repository's name and link are built into the page; its description,
+// star count and fork count are fetched from the public GitHub API when the
+// page loads, as on Mintlify. The unauthenticated API allows 60 requests an
+// hour per reader's IP, so the response is cached for the browser session.
+// If the request fails, the card stays a plain link to the repository.
+import AppIcon from './AppIcon.astro';
+
+interface Props {
+  repo: string;
+  variant?: 'inset' | 'flat';
+}
+const { repo, variant = 'inset' } = Astro.props as Props;
+const slug = String(repo ?? '')
+  .trim()
+  .replace(/^(?:https?:\/\/)?(?:www\.)?github\.com\//i, '')
+  .replace(/\.git$/i, '')
+  .split(/[/?#]/)
+  .slice(0, 2)
+  .join('/');
+const valid = /^[\w.-]+\/[\w.-]+$/.test(slug);
+---
+{valid && (
+  <a
+    class:list={['wd-github-repo', `wd-github-repo-${variant}`]}
+    href={`https://github.com/${slug}`}
+    target="_blank"
+    rel="noopener noreferrer"
+    data-repo={slug}
+  >
+    <div class="wd-github-repo-inner">
+      <div class="wd-github-repo-name">
+        <AppIcon icon="fa6-brands:github" class="wd-github-repo-icon" />
+        <span>{slug}</span>
+      </div>
+      <p class="wd-github-repo-description" hidden></p>
+      <div class="wd-github-repo-stats" hidden>
+        <span><span aria-hidden="true">&#9733;</span> <span data-stat="stars"></span> stars</span>
+        <span><span data-stat="forks"></span> forks</span>
+      </div>
+    </div>
+  </a>
+)}
+<script>
+  type RepoInfo = { description: string | null; stargazers_count: number; forks_count: number };
+  const compact = (n: number) =>
+    new Intl.NumberFormat('en', { notation: 'compact', maximumFractionDigits: 1 }).format(n);
+
+  async function loadRepo(slug: string): Promise<RepoInfo | null> {
+    const key = `wd-github-repo:${slug}`;
+    try {
+      const cached = sessionStorage.getItem(key);
+      if (cached) return JSON.parse(cached);
+    } catch {}
+    try {
+      const res = await fetch(`https://api.github.com/repos/${slug}`, {
+        headers: { Accept: 'application/vnd.github+json' },
+      });
+      if (!res.ok) return null;
+      const data = await res.json();
+      const info: RepoInfo = {
+        description: data.description ?? null,
+        stargazers_count: data.stargazers_count ?? 0,
+        forks_count: data.forks_count ?? 0,
+      };
+      try {
+        sessionStorage.setItem(key, JSON.stringify(info));
+      } catch {}
+      return info;
+    } catch {
+      return null;
+    }
+  }
+
+  function initGitHubRepos(root: ParentNode) {
+    root.querySelectorAll<HTMLElement>('.wd-github-repo[data-repo]').forEach(async (card) => {
+      if (card.dataset.wdInit) return;
+      card.dataset.wdInit = 'true';
+      const info = await loadRepo(card.dataset.repo!);
+      if (!info) return;
+      const desc = card.querySelector<HTMLElement>('.wd-github-repo-description');
+      if (desc && info.description) {
+        desc.textContent = info.description;
+        desc.hidden = false;
+      }
+      const stats = card.querySelector<HTMLElement>('.wd-github-repo-stats');
+      if (stats) {
+        stats.querySelector('[data-stat="stars"]')!.textContent = compact(info.stargazers_count);
+        stats.querySelector('[data-stat="forks"]')!.textContent = compact(info.forks_count);
+        stats.hidden = false;
+      }
+    });
+  }
+  initGitHubRepos(document);
+  document.addEventListener('astro:page-load', () => initGitHubRepos(document));
+</script>
+<style>
+  .wd-github-repo {
+    display: block;
+    margin: 1.25rem 0;
+    border: 1px solid var(--wd-border);
+    border-radius: 0.75rem;
+    text-decoration: none;
+    color: inherit;
+    transition: border-color 0.15s ease;
+  }
+  .wd-github-repo:hover {
+    border-color: var(--wd-primary);
+  }
+  /* inset (the default): the details sit on a rounded inner surface. */
+  .wd-github-repo-inset {
+    padding: 0.4rem;
+  }
+  .wd-github-repo-inset .wd-github-repo-inner {
+    padding: 0.9rem 1rem;
+    border-radius: 0.5rem;
+    background: var(--wd-surface);
+  }
+  /* flat: one surface, tighter padding. */
+  .wd-github-repo-flat .wd-github-repo-inner {
+    padding: 0.75rem 0.9rem;
+  }
+  .wd-github-repo-name {
+    display: flex;
+    align-items: center;
+    gap: 0.5rem;
+    font-weight: 600;
+    color: var(--wd-text);
+  }
+  :global(svg.wd-github-repo-icon) {
+    width: 1.1rem;
+    height: 1.1rem;
+    flex-shrink: 0;
+  }
+  .wd-github-repo-description {
+    margin: 0.4rem 0 0;
+    font-size: 0.875rem;
+    color: var(--wd-text-muted);
+  }
+  .wd-github-repo-stats {
+    display: flex;
+    gap: 1rem;
+    margin-top: 0.5rem;
+    font-size: 0.8rem;
+    color: var(--wd-text-muted);
+  }
+  .wd-github-repo-stats[hidden],
+  .wd-github-repo-description[hidden] {
+    display: none;
+  }
+</style>

package/src/components/Panel.astro

@@ -0,0 +1,11 @@
+---
+// Mintlify's <Panel> - content pinned to the right-hand column on desktop,
+// in place of the table of contents. It's the same docking
+// RequestExample/ResponseExample already use (initExamplePanels() in
+// [...slug].astro): the `wd-example-panel` class is what that script moves
+// into the column at >= 1151px wide, and back into the page below that.
+// A RequestExample/ResponseExample inside a Panel moves with it. On a page
+// with no table-of-contents column (any mode but `default`), the Panel
+// stays where it is in the page.
+---
+<div class="wd-example-panel wd-panel"><slot /></div>

package/src/components/Prompt.astro

@@ -0,0 +1,143 @@
+---
+// Mintlify's <Prompt> - a ready-made AI prompt: a card showing
+// `description` (inline Markdown) and an optional icon, with actions to
+// copy the prompt or open it in Cursor. The prompt itself is the slot; it's
+// also viewable in a collapsed "Show prompt" section under the card.
+//
+// What gets copied/sent is the prompt's *source* text - `_text`, read from
+// the MDX file by remarkMintlifyPromptText (lib/mdx-mintlify.js) - so its
+// Markdown survives. Without it (a Prompt used outside MDX), the copy falls
+// back to the rendered text.
+//
+// `actions` defaults to ["copy"]; add "cursor" for an "Open in Cursor"
+// link (Cursor's own https://cursor.com/link/prompt?text=... deeplink,
+// which also works for readers without Cursor installed). Cursor caps a
+// deeplink at 10,000 URL-encoded characters, so a longer prompt gets no
+// Cursor link - just the copy button.
+import AppIcon from './AppIcon.astro';
+import { inlineMarkdown } from '../lib/inline-markdown.js';
+
+interface Props {
+  description?: string;
+  icon?: string;
+  actions?: Array<'copy' | 'cursor'>;
+  _text?: string;
+}
+const { description, icon, actions = ['copy'], _text } = Astro.props as Props;
+const cursorHref = _text ? `https://cursor.com/link/prompt?text=${encodeURIComponent(_text)}` : null;
+const showCursor = actions.includes('cursor') && cursorHref !== null && cursorHref.length <= 10000;
+---
+<div class="wd-prompt">
+  <div class="wd-prompt-head">
+    {icon && <AppIcon icon={icon} class="wd-prompt-icon" />}
+    {description && <div class="wd-prompt-description" set:html={inlineMarkdown(description)} />}
+    <div class="wd-prompt-actions">
+      {actions.includes('copy') && (
+        <button type="button" class="wd-prompt-action" data-role="copy-prompt">Copy prompt</button>
+      )}
+      {showCursor && (
+        <a class="wd-prompt-action" href={cursorHref} target="_blank" rel="noopener noreferrer">Open in Cursor</a>
+      )}
+    </div>
+  </div>
+  <details class="wd-prompt-text">
+    <summary>Show prompt</summary>
+    <div class="wd-prompt-body"><slot /></div>
+  </details>
+  {_text && <template class="wd-prompt-source">{_text}</template>}
+</div>
+<script>
+  function initPrompts(root: ParentNode) {
+    root.querySelectorAll<HTMLButtonElement>('[data-role="copy-prompt"]').forEach((btn) => {
+      if (btn.dataset.wdInit) return;
+      btn.dataset.wdInit = 'true';
+      btn.addEventListener('click', async () => {
+        const card = btn.closest('.wd-prompt');
+        const source = card?.querySelector<HTMLTemplateElement>('template.wd-prompt-source');
+        const text = source ? source.content.textContent ?? '' : card?.querySelector('.wd-prompt-body')?.textContent?.trim() ?? '';
+        try {
+          await navigator.clipboard.writeText(text);
+          btn.textContent = 'Copied';
+        } catch {
+          btn.textContent = 'Copy failed';
+        }
+        setTimeout(() => (btn.textContent = 'Copy prompt'), 1500);
+      });
+    });
+  }
+  initPrompts(document);
+  document.addEventListener('astro:page-load', () => initPrompts(document));
+</script>
+<style>
+  .wd-prompt {
+    margin: 1.25rem 0;
+    border: 1px solid var(--wd-border);
+    border-radius: 0.6rem;
+    overflow: hidden;
+  }
+  .wd-prompt-head {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    padding: 0.9rem 1.1rem;
+  }
+  :global(svg.wd-prompt-icon),
+  :global(span.wd-prompt-icon) {
+    flex-shrink: 0;
+    width: 1.1rem;
+    height: 1.1rem;
+    color: var(--wd-primary);
+  }
+  .wd-prompt-description {
+    flex: 1;
+    min-width: 0;
+    color: var(--wd-text);
+  }
+  .wd-prompt-actions {
+    display: flex;
+    flex-shrink: 0;
+    gap: 0.4rem;
+  }
+  .wd-prompt-action {
+    padding: 0.3rem 0.7rem;
+    border: 1px solid var(--wd-border);
+    border-radius: 0.4rem;
+    background: var(--wd-background);
+    color: var(--wd-text);
+    font-size: 0.8rem;
+    text-decoration: none;
+    cursor: pointer;
+    white-space: nowrap;
+  }
+  .wd-prompt-action:hover {
+    border-color: var(--wd-primary);
+    color: var(--wd-primary);
+  }
+  .wd-prompt-text {
+    border-top: 1px solid var(--wd-border);
+    background: var(--wd-surface);
+  }
+  .wd-prompt-text summary {
+    padding: 0.5rem 1.1rem;
+    font-size: 0.8rem;
+    color: var(--wd-text-muted);
+    cursor: pointer;
+  }
+  .wd-prompt-body {
+    padding: 0 1.1rem 0.9rem;
+    font-size: 0.9rem;
+    color: var(--wd-text-muted);
+  }
+  .wd-prompt-body :global(p:first-child) {
+    margin-top: 0;
+  }
+  .wd-prompt-body :global(p:last-child),
+  .wd-prompt-body :global(ul:last-child) {
+    margin-bottom: 0;
+  }
+  @media (max-width: 640px) {
+    .wd-prompt-head {
+      flex-wrap: wrap;
+    }
+  }
+</style>

package/src/components/Tile.astro

@@ -0,0 +1,65 @@
+---
+// Mintlify's <Tile> - a visual preview (the slot, usually an image or a
+// light/dark image pair) on a patterned background, with a title and
+// description under it. Usually laid out in a <Columns> grid. `title`
+// takes inline Markdown (`code`, **bold**, *italic*), like Mintlify's.
+import { inlineMarkdown } from '../lib/inline-markdown.js';
+
+interface Props {
+  href?: string;
+  title?: string;
+  description?: string;
+}
+const { href, title, description } = Astro.props as Props;
+const Tag = href ? 'a' : 'div';
+---
+<Tag class="wd-tile" href={href}>
+  <div class="wd-tile-preview"><slot /></div>
+  {title && <div class="wd-tile-title" set:html={inlineMarkdown(title)} />}
+  {description && <div class="wd-tile-description">{description}</div>}
+</Tag>
+<style>
+  .wd-tile {
+    display: block;
+    text-decoration: none;
+    color: inherit;
+  }
+  /* Dotted pattern behind the preview, drawn from the theme's own border
+     color so it reads in both themes. */
+  .wd-tile-preview {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    height: 10rem;
+    overflow: hidden;
+    border: 1px solid var(--wd-border);
+    border-radius: 0.6rem;
+    background-color: var(--wd-surface);
+    background-image: radial-gradient(var(--wd-border) 1px, transparent 1px);
+    background-size: 14px 14px;
+    transition: border-color 0.15s ease;
+  }
+  a.wd-tile:hover .wd-tile-preview {
+    border-color: var(--wd-primary);
+  }
+  .wd-tile-preview :global(img),
+  .wd-tile-preview :global(svg) {
+    max-width: 100%;
+    max-height: 100%;
+    object-fit: contain;
+    margin: 0;
+  }
+  .wd-tile-preview :global(p) {
+    display: contents;
+  }
+  .wd-tile-title {
+    margin-top: 0.6rem;
+    font-weight: 600;
+    color: var(--wd-text);
+  }
+  .wd-tile-description {
+    margin-top: 0.15rem;
+    font-size: 0.875rem;
+    color: var(--wd-text-muted);
+  }
+</style>