@writedocs/generator 0.4.6 → 0.4.8

package/src/components/View.astro

@@ -0,0 +1,214 @@
+---
+// Mintlify's <View title="..." icon="..."> - content for one of several
+// alternatives (a language, a framework) on the same page. Every distinct
+// `title` on the page becomes an option in one switcher, placed under the
+// page title (or before the first View on a page without one); only the
+// selected title's Views show. As on Mintlify, the table of contents only
+// lists the headings in the visible Views.
+//
+// The choice is remembered (localStorage) across pages, so a reader who
+// picks "Python" keeps seeing Python wherever the same title exists. A
+// link to an anchor inside a hidden View switches to that View first.
+import AppIcon from './AppIcon.astro';
+interface Props {
+  title: string;
+  icon?: string;
+}
+const { title, icon } = Astro.props as Props;
+---
+<div class="wd-view" data-view-title={title}>
+  {icon && <span class="wd-view-icon-src" hidden><AppIcon icon={icon} class="wd-view-icon" /></span>}
+  <slot />
+</div>
+<script>
+  const STORAGE_KEY = 'wd-view';
+
+  function initViews(root: Document) {
+    const views = Array.from(root.querySelectorAll<HTMLElement>('.wd-view[data-view-title]'));
+    if (views.length === 0 || root.querySelector('.wd-view-switcher')) return;
+
+    const titles = [...new Set(views.map((v) => v.dataset.viewTitle!))];
+    const iconFor = (title: string) =>
+      views.find((v) => v.dataset.viewTitle === title)?.querySelector<HTMLElement>('.wd-view-icon-src > *') ?? null;
+
+    let stored: string | null = null;
+    try {
+      stored = localStorage.getItem(STORAGE_KEY);
+    } catch {}
+    const hashTarget = location.hash ? document.getElementById(decodeURIComponent(location.hash.slice(1))) : null;
+    const hashView = hashTarget?.closest<HTMLElement>('.wd-view')?.dataset.viewTitle;
+    let current = hashView ?? (stored && titles.includes(stored) ? stored : titles[0]);
+
+    // The switcher: a button showing the current option, and a menu of all.
+    const switcher = document.createElement('div');
+    switcher.className = 'wd-view-switcher';
+    const button = document.createElement('button');
+    button.type = 'button';
+    button.className = 'wd-view-button';
+    button.setAttribute('aria-haspopup', 'listbox');
+    button.setAttribute('aria-expanded', 'false');
+    const menu = document.createElement('ul');
+    menu.className = 'wd-view-menu';
+    menu.setAttribute('role', 'listbox');
+    menu.hidden = true;
+
+    const label = (title: string) => {
+      const frag = document.createDocumentFragment();
+      const icon = iconFor(title);
+      if (icon) frag.appendChild(icon.cloneNode(true));
+      frag.appendChild(document.createTextNode(title));
+      return frag;
+    };
+    const options = titles.map((title) => {
+      const li = document.createElement('li');
+      li.setAttribute('role', 'option');
+      li.tabIndex = -1;
+      li.dataset.viewTitle = title;
+      li.appendChild(label(title));
+      li.addEventListener('click', () => {
+        select(title, true);
+        close();
+        button.focus();
+      });
+      li.addEventListener('keydown', (e) => {
+        const i = options.indexOf(li);
+        if (e.key === 'ArrowDown') options[Math.min(i + 1, options.length - 1)].focus();
+        else if (e.key === 'ArrowUp') options[Math.max(i - 1, 0)].focus();
+        else if (e.key === 'Enter' || e.key === ' ') li.click();
+        else if (e.key === 'Escape') {
+          close();
+          button.focus();
+        } else return;
+        e.preventDefault();
+      });
+      menu.appendChild(li);
+      return li;
+    });
+
+    const open = () => {
+      menu.hidden = false;
+      button.setAttribute('aria-expanded', 'true');
+      (options.find((o) => o.dataset.viewTitle === current) ?? options[0]).focus();
+    };
+    const close = () => {
+      menu.hidden = true;
+      button.setAttribute('aria-expanded', 'false');
+    };
+    button.addEventListener('click', () => (menu.hidden ? open() : close()));
+    document.addEventListener('click', (e) => {
+      if (!switcher.contains(e.target as Node)) close();
+    });
+
+    function select(title: string, remember: boolean) {
+      current = title;
+      views.forEach((v) => (v.hidden = v.dataset.viewTitle !== title));
+      button.replaceChildren(label(title));
+      const chevron = document.createElement('span');
+      chevron.className = 'wd-view-chevron';
+      chevron.setAttribute('aria-hidden', 'true');
+      button.appendChild(chevron);
+      options.forEach((o) => o.setAttribute('aria-selected', String(o.dataset.viewTitle === title)));
+      // Table of contents: only headings the reader can currently see.
+      document.querySelectorAll<HTMLAnchorElement>('.wd-toc a[data-toc-slug]').forEach((a) => {
+        const heading = document.getElementById(a.dataset.tocSlug ?? '');
+        const li = a.closest('li');
+        if (li) li.hidden = Boolean(heading?.closest('.wd-view[hidden]'));
+      });
+      if (remember) {
+        try {
+          localStorage.setItem(STORAGE_KEY, title);
+        } catch {}
+      }
+    }
+
+    switcher.append(button, menu);
+    const header = document.querySelector('.wd-article-header');
+    if (header) header.after(switcher);
+    else views[0].before(switcher);
+    select(current, false);
+    if (hashTarget && hashView) hashTarget.scrollIntoView();
+
+    // Same for an in-page link to an anchor inside a hidden View.
+    window.addEventListener('hashchange', () => {
+      if (!switcher.isConnected) return;
+      const el = location.hash ? document.getElementById(decodeURIComponent(location.hash.slice(1))) : null;
+      const title = el?.closest<HTMLElement>('.wd-view[hidden]')?.dataset.viewTitle;
+      if (!title) return;
+      select(title, false);
+      el!.scrollIntoView();
+    });
+  }
+  initViews(document);
+  document.addEventListener('astro:page-load', () => initViews(document));
+</script>
+<style>
+  .wd-view[hidden] {
+    display: none;
+  }
+  :global(.wd-view-switcher) {
+    position: relative;
+    display: inline-block;
+    margin: 0 0 1rem;
+  }
+  :global(.wd-view-button) {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.45rem;
+    padding: 0.35rem 0.75rem;
+    border: 1px solid var(--wd-border);
+    border-radius: 0.5rem;
+    background: var(--wd-background);
+    color: var(--wd-text);
+    font-size: 0.875rem;
+    cursor: pointer;
+  }
+  :global(.wd-view-button:hover) {
+    border-color: var(--wd-primary);
+  }
+  :global(.wd-view-chevron) {
+    width: 0.4rem;
+    height: 0.4rem;
+    margin-left: 0.2rem;
+    border-right: 1.5px solid currentColor;
+    border-bottom: 1.5px solid currentColor;
+    transform: translateY(-2px) rotate(45deg);
+  }
+  :global(.wd-view-menu) {
+    position: absolute;
+    top: calc(100% + 0.3rem);
+    left: 0;
+    z-index: 20;
+    min-width: 100%;
+    margin: 0;
+    padding: 0.3rem;
+    list-style: none;
+    border: 1px solid var(--wd-border);
+    border-radius: 0.5rem;
+    background: var(--wd-background);
+    box-shadow: 0 6px 20px rgba(0, 0, 0, 0.12);
+  }
+  :global(.wd-view-menu li) {
+    display: flex;
+    align-items: center;
+    gap: 0.45rem;
+    margin: 0;
+    padding: 0.35rem 0.6rem;
+    border-radius: 0.35rem;
+    font-size: 0.875rem;
+    white-space: nowrap;
+    cursor: pointer;
+  }
+  :global(.wd-view-menu li:hover),
+  :global(.wd-view-menu li:focus),
+  :global(.wd-view-menu li[aria-selected='true']) {
+    outline: none;
+    background: color-mix(in srgb, var(--wd-primary) 10%, transparent);
+    color: var(--wd-primary);
+  }
+  :global(svg.wd-view-icon),
+  :global(span.wd-view-icon) {
+    width: 1em;
+    height: 1em;
+    flex-shrink: 0;
+  }
+</style>

package/src/components/Visibility.astro

@@ -0,0 +1,11 @@
+---
+// Mintlify's <Visibility for="humans|agents">. On the rendered site,
+// `humans` content shows and `agents` content doesn't; the per-page `.md`
+// route and llms-full.txt do the opposite (see lib/visibility.js). A
+// <Visibility> with no `for` counts as `humans`.
+interface Props {
+  for?: 'humans' | 'agents';
+}
+const { for: audience = 'humans' } = Astro.props as Props;
+---
+{audience !== 'agents' && <slot />}

package/src/components/compound.ts

@@ -0,0 +1,21 @@
+// Mintlify's dotted component names - <Tree.Folder>, <Color.Item>,
+// <GitHub.Repo>, ... MDX compiles <Tree.Folder> to a property lookup on
+// whatever `Tree` resolves to, so the parts are attached as properties of
+// their parent here, once, and everything that hands components to MDX (the
+// src/components/index.ts barrel and [...slug].astro's `components` map)
+// takes these three from this module rather than importing the .astro files
+// directly. `FileTree` is Mintlify's other name for `Tree`.
+import TreeRoot from './Tree.astro';
+import TreeFolder from './TreeFolder.astro';
+import TreeFile from './TreeFile.astro';
+import ColorRoot from './Color.astro';
+import ColorRow from './ColorRow.astro';
+import ColorItem from './ColorItem.astro';
+import GitHubRepo from './GitHubRepo.astro';
+
+export const Tree = Object.assign(TreeRoot, { Folder: TreeFolder, File: TreeFile });
+export const FileTree = Tree;
+export const Color = Object.assign(ColorRoot, { Row: ColorRow, Item: ColorItem });
+// Mintlify has no bare <GitHub> - only <GitHub.Repo> - so this is just a
+// namespace object, not a component.
+export const GitHub = { Repo: GitHubRepo };

package/src/components/index.ts

@@ -46,3 +46,15 @@ export { default as Badge } from './Badge.astro';
 export { default as Icon } from './Icon.astro';
 export { default as RequestExample } from './RequestExample.astro';
 export { default as ResponseExample } from './ResponseExample.astro';
+export { default as Check } from './Check.astro';
+export { default as ParamField } from './ParamField.astro';
+export { default as ResponseField } from './ResponseField.astro';
+export { default as Columns } from './Columns.astro';
+export { default as Tooltip } from './Tooltip.astro';
+export { default as Update } from './Update.astro';
+export { default as Tile } from './Tile.astro';
+export { default as Panel } from './Panel.astro';
+export { default as Prompt } from './Prompt.astro';
+export { default as View } from './View.astro';
+export { default as Visibility } from './Visibility.astro';
+export { Tree, FileTree, Color, GitHub } from './compound';

package/src/content.config.ts

@@ -32,6 +32,8 @@ const contentDir = process.env.WRITEDOCS_CONTENT_DIR || process.cwd();
 const generatedDocsDir = path.join(writedocsTempDir(contentDir), 'generated-docs');
 const generatedDocsBase = pathToFileURL(generatedDocsDir + path.sep);
 
+const MINTLIFY_MODE_ALIASES: Record<string, string> = { center: 'frame', assistant: 'default' };
+
 const docsSchema = z.object({
   title: z.string(),
   description: z.string().optional(),
@@ -82,7 +84,19 @@ const docsSchema = z.object({
   //             chrome at all, just <slot />. For a page that wants to
   //             look nothing like the rest of the site (an auth screen,
   //             a print-style page).
-  mode: z.enum(['default', 'wide', 'frame', 'custom', 'blank']).default('default'),
+  //
+  // Two Mintlify values are accepted so a migrated page doesn't fail the
+  // build (see MINTLIFY_MODE_ALIASES below): `center` is the same layout
+  // as our `frame`, and `assistant` (a full-page Mintlify AI chat, which
+  // writedocs doesn't have) falls back to `default`. Mintlify's own
+  // `frame` means something else (a canvas that keeps the sidebar) - it's
+  // left as our `frame`; see docs/dev/docs/mintlify-compat.mdx.
+  mode: z
+    .preprocess(
+      (value) => (typeof value === 'string' && value in MINTLIFY_MODE_ALIASES ? MINTLIFY_MODE_ALIASES[value] : value),
+      z.enum(['default', 'wide', 'frame', 'custom', 'blank']),
+    )
+    .default('default'),
   // Per-page meta tag overrides - same shape as writedocs.json's top-level
   // `seo` (see seoFieldsSchema in lib/config.ts, the single source of
   // truth for this shape). A page only needs to set the specific fields
@@ -90,7 +104,59 @@ const docsSchema = z.object({
   // for anything left unset. See BaseLayout.astro for where this and the
   // site-wide seo actually get merged and rendered.
   seo: seoFieldsSchema.optional(),
-});
+  // Mintlify's spelling of `seo.noindex` - a top-level `noindex: true`.
+  // Folded into `seo` by the transform below, so everything downstream
+  // (the robots meta tag, sitemap.xml, llms.txt) keeps reading
+  // `seo.noindex` only.
+  noindex: z.boolean().optional(),
+  // Mintlify's short navigation label - used for the sidebar and the
+  // topbar dropdown menus in place of `title` ([...slug].astro's
+  // navTitleForSlug). The page's own <h1> and prev/next links keep `title`.
+  sidebarTitle: z.string().optional(),
+  // Mintlify's spellings of `seo.keywords`, `seo.ogImage`, `seo.ogType`
+  // and `seo.twitterCard`, folded into `seo` below like `noindex`.
+  keywords: z.array(z.string()).optional(),
+  'og:image': z.string().optional(),
+  'og:type': z.string().optional(),
+  'twitter:card': z.enum(['summary', 'summary_large_image']).optional(),
+  // Mintlify's sidebar/page-chrome fields - see NavTree.astro and
+  // [...slug].astro for where each is used:
+  //   icon                 - shown before the page's label in the sidebar.
+  //   tag                  - a short label after it (e.g. "NEW").
+  //   deprecated           - a "Deprecated" label in the sidebar and next
+  //                          to the page's <h1>.
+  //   hidden               - left out of the sidebar, dropdowns and
+  //                          prev/next, but still built and reachable by
+  //                          URL. Also noindexed, as on Mintlify.
+  //   url                  - an external link: the page's sidebar entry
+  //                          links straight to it, and the page's own URL
+  //                          redirects there.
+  //   hideFooterPagination - no prev/next links on this page.
+  //   hideApiMarker        - no HTTP method badge on this page's sidebar
+  //                          entry.
+  icon: z.string().optional(),
+  tag: z.string().optional(),
+  deprecated: z.boolean().optional(),
+  hidden: z.boolean().optional(),
+  url: z.string().optional(),
+  hideFooterPagination: z.boolean().optional(),
+  hideApiMarker: z.boolean().optional(),
+}).transform(
+  ({ noindex, keywords, 'og:image': ogImage, 'og:type': ogType, 'twitter:card': twitterCard, ...data }) => {
+    // Top-level Mintlify keys fill in `seo` only where the page's own `seo`
+    // doesn't already set that field - an explicit `seo` value always wins.
+    // A `hidden` page is noindexed unless it says otherwise.
+    const fromMintlify = { noindex: noindex ?? (data.hidden ? true : undefined), keywords, ogImage, ogType, twitterCard };
+    const seo = { ...data.seo };
+    let changed = false;
+    for (const [key, value] of Object.entries(fromMintlify)) {
+      if (value === undefined || seo[key as keyof typeof seo] !== undefined) continue;
+      (seo as Record<string, unknown>)[key] = value;
+      changed = true;
+    }
+    return changed ? { ...data, seo } : data;
+  },
+);
 
 /** Wraps another loader so it's skipped entirely - no filesystem scan, no
  *  "directory doesn't exist"/"no files found" warning - when its own base

package/src/layout/components/NavTree.astro

@@ -1,5 +1,6 @@
 ---
 import { navTreeContainsSlug, isExternalHref, type NavTreeNode } from "../../lib/config";
+import AppIcon from "../../components/AppIcon.astro";
 import { methodClass } from "../../lib/openapi-render";
 
 interface Props {
@@ -22,7 +23,10 @@ const { nodes, hrefForSlug, currentSlug, depth = 0 } = Astro.props as Props;
               {node.method && (
                 <span class={`wd-nav-method wd-nav-method-${methodClass(node.method)}`}>{node.method}</span>
               )}
+              {node.icon && <AppIcon icon={node.icon} class="wd-nav-page-icon" />}
               <span class="wd-nav-title">{node.title}</span>
+              {node.deprecated && <span class="wd-nav-tag wd-nav-tag-deprecated">Deprecated</span>}
+              {node.tag && <span class="wd-nav-tag">{node.tag}</span>}
             </a>
           </li>
         );
@@ -227,6 +231,36 @@ const { nodes, hrefForSlug, currentSlug, depth = 0 } = Astro.props as Props;
     /* text-overflow: ellipsis;
     white-space: nowrap; */
   }
+  /* A page's own frontmatter `icon` (Mintlify's) - :global() because
+     AppIcon.astro renders the svg/span, not this component. */
+  :global(svg.wd-nav-page-icon),
+  :global(span.wd-nav-page-icon) {
+    flex-shrink: 0;
+    width: 1em;
+    height: 1em;
+  }
+  :global(span.wd-nav-page-icon) {
+    display: flex;
+    align-items: center;
+    justify-content: center;
+  }
+  /* Frontmatter `tag` / `deprecated` - a small pill after the title, same
+     shape as the method badge. */
+  .wd-nav-tag {
+    flex-shrink: 0;
+    padding: 0.05rem 0.4rem;
+    border-radius: 999px;
+    font-size: 0.62rem;
+    font-weight: 700;
+    line-height: 1.5;
+    letter-spacing: 0.02em;
+    color: var(--wd-primary);
+    background: color-mix(in srgb, var(--wd-primary) 12%, transparent);
+  }
+  .wd-nav-tag-deprecated {
+    color: #d97706;
+    background: color-mix(in srgb, #d97706 15%, transparent);
+  }
   .wd-nav-method {
     flex-shrink: 0;
     display: inline-block;

package/src/layout/styles/base.css

@@ -232,3 +232,15 @@ pre {
   font-weight: var(--shiki-dark-font-weight) !important;
   text-decoration: var(--shiki-dark-text-decoration) !important;
 }
+
+/* An icon given as an image URL or path (resolveIcon()'s 'image' kind,
+   rendered by AppIcon.astro) - 1em square inside its caller's own icon
+   span, so it sizes like a glyph icon would. Lives here rather than in
+   AppIcon.astro so it's part of the shared stylesheet, not an inline
+   <style> added to every page. */
+img.wd-icon-img {
+  display: block;
+  width: 1em;
+  height: 1em;
+  object-fit: contain;
+}