@writedocs/generator 0.4.6 → 0.4.7

package/src/components/Tabs.astro

@@ -1,4 +1,11 @@
-<div class="wd-tabs">
+---
+// `defaultTabIndex` is Mintlify's: which tab (0-based) starts selected.
+interface Props {
+  defaultTabIndex?: number;
+}
+const { defaultTabIndex = 0 } = Astro.props as Props;
+---
+<div class="wd-tabs" data-default-index={defaultTabIndex}>
   <slot />
 </div>
 <script>
@@ -7,13 +14,20 @@
       if (tabs.dataset.wdInit) return;
       tabs.dataset.wdInit = 'true';
       const panels = Array.from(tabs.querySelectorAll<HTMLElement>(':scope > .wd-tab'));
+      const requested = Number(tabs.dataset.defaultIndex ?? 0);
+      const initial = Number.isInteger(requested) && requested >= 0 && requested < panels.length ? requested : 0;
       const nav = document.createElement('div');
       nav.className = 'wd-tabs-nav';
       panels.forEach((panel, i) => {
         const btn = document.createElement('button');
         btn.type = 'button';
-        btn.textContent = panel.dataset.title ?? `Tab ${i + 1}`;
-        btn.className = 'wd-tabs-btn' + (i === 0 ? ' active' : '');
+        // A Tab's `icon` is rendered server-side (astro-icon only runs at
+        // build time) into a hidden holder inside the panel - see
+        // Tab.astro - and moved into its button here.
+        const icon = panel.querySelector<HTMLElement>(':scope > .wd-tab-icon-src > *');
+        if (icon) btn.appendChild(icon);
+        btn.appendChild(document.createTextNode(panel.dataset.title ?? `Tab ${i + 1}`));
+        btn.className = 'wd-tabs-btn' + (i === initial ? ' active' : '');
         btn.addEventListener('click', () => {
           nav.querySelectorAll('.wd-tabs-btn').forEach((b) => b.classList.remove('active'));
           panels.forEach((p) => (p.style.display = 'none'));
@@ -21,7 +35,7 @@
           panel.style.display = 'block';
         });
         nav.appendChild(btn);
-        panel.style.display = i === 0 ? 'block' : 'none';
+        panel.style.display = i === initial ? 'block' : 'none';
       });
       tabs.prepend(nav);
     });
@@ -45,6 +59,15 @@
     color: var(--wd-text-muted);
     border-bottom: 2px solid transparent;
   }
+  .wd-tabs-btn {
+    display: inline-flex;
+    align-items: center;
+    gap: 0.4rem;
+  }
+  svg.wd-tabs-btn-icon {
+    width: 1em;
+    height: 1em;
+  }
   .wd-tabs-btn.active {
     color: var(--wd-primary);
     border-bottom-color: var(--wd-primary);

package/src/components/Tooltip.astro

@@ -0,0 +1,13 @@
+---
+// Mintlify's <Tooltip tip headline cta href> - rendered by Hint.astro,
+// which is the same inline hover bubble under writedocs' own name.
+import Hint from './Hint.astro';
+interface Props {
+  tip: string;
+  headline?: string;
+  cta?: string;
+  href?: string;
+}
+const props = Astro.props as Props;
+---
+<Hint {...props}><slot /></Hint>

package/src/components/index.ts

@@ -46,3 +46,8 @@ 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';

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;
+}