@writedocs/generator 0.9.3 → 0.9.4

package/package.json

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

package/src/components/ApiPlayground.astro

@@ -13,6 +13,7 @@ import {
   type OpenApiOperation,
 } from '../lib/openapi-render';
 import { parseOpenApiRef } from '../lib/openapi-ref.js';
+import { descriptionHtml } from '../lib/openapi-markdown';
 
 interface Props {
   operation: string; // "METHOD /path", matching a page's `openapi` frontmatter
@@ -37,6 +38,12 @@ const requestRows = requestSchema ? schemaRows(requestSchema) : [];
 
 const responseEntries = op ? Object.entries(op.responses) : [];
 const segments = op ? pathSegments(op.path) : [];
+
+// Descriptions are Markdown in the spec - rendered here, once each
+// (lib/openapi-markdown.ts), and set as HTML below.
+const operationHtml = await descriptionHtml(op?.description);
+const paramHtml = new Map(await Promise.all((op?.parameters ?? []).map(async (p) => [p, await descriptionHtml(p.description)] as const)));
+const responseHtml = new Map(await Promise.all(responseEntries.map(async ([status, r]) => [status, await descriptionHtml(r.description)] as const)));
 ---
 
 {!op && (
@@ -57,7 +64,7 @@ const segments = op ? pathSegments(op.path) : [];
         )}
       </code>
     </div>
-    {op.description && <p class="wd-api-description">{op.description}</p>}
+    {operationHtml && <div class="wd-api-description wd-api-md" set:html={operationHtml} />}
 
     {headerParams.length > 0 && (
       <section class="wd-api-section">
@@ -70,7 +77,7 @@ const segments = op ? pathSegments(op.path) : [];
                 <span class="wd-api-pill wd-api-pill-type">{p.schema?.type ?? 'string'}</span>
                 {p.required && <span class="wd-api-pill wd-api-pill-required">required</span>}
               </div>
-              {p.description && <p class="wd-api-param-desc">{p.description}</p>}
+              {paramHtml.get(p) && <div class="wd-api-param-desc wd-api-md" set:html={paramHtml.get(p)} />}
             </div>
           ))}
         </div>
@@ -88,7 +95,7 @@ const segments = op ? pathSegments(op.path) : [];
                 <span class="wd-api-pill wd-api-pill-type">{p.schema?.type ?? 'string'}</span>
                 {p.required && <span class="wd-api-pill wd-api-pill-required">required</span>}
               </div>
-              {p.description && <p class="wd-api-param-desc">{p.description}</p>}
+              {paramHtml.get(p) && <div class="wd-api-param-desc wd-api-md" set:html={paramHtml.get(p)} />}
             </div>
           ))}
         </div>
@@ -106,7 +113,7 @@ const segments = op ? pathSegments(op.path) : [];
                 <span class="wd-api-pill wd-api-pill-type">{p.schema?.type ?? 'string'}</span>
                 {p.required && <span class="wd-api-pill wd-api-pill-required">required</span>}
               </div>
-              {p.description && <p class="wd-api-param-desc">{p.description}</p>}
+              {paramHtml.get(p) && <div class="wd-api-param-desc wd-api-md" set:html={paramHtml.get(p)} />}
             </div>
           ))}
         </div>
@@ -132,8 +139,8 @@ const segments = op ? pathSegments(op.path) : [];
             const rows = schema ? schemaRows(schema) : [];
             return (
               <Tab title={status}>
-                {resp.description && (
-                  <p class="wd-api-param-desc-inline wd-api-response-desc">{resp.description}</p>
+                {responseHtml.get(status) && (
+                  <div class="wd-api-param-desc-inline wd-api-response-desc wd-api-md" set:html={responseHtml.get(status)} />
                 )}
                 {rows.length > 0 && (
                   <div class="wd-api-param-list wd-api-param-list-nested">
@@ -282,4 +289,38 @@ const segments = op ? pathSegments(op.path) : [];
   .wd-api-response-desc {
     margin: 0 0 0.75rem;
   }
+  /* A description from the spec, rendered from its Markdown
+     (lib/openapi-markdown.ts) - paragraphs, lists, code and tables sized
+     to sit under a field. A wide table scrolls sideways inside its own box
+     rather than widening the page. */
+  .wd-api-md > :first-child {
+    margin-top: 0;
+  }
+  .wd-api-md > :last-child {
+    margin-bottom: 0;
+  }
+  .wd-api-md p,
+  .wd-api-md ul,
+  .wd-api-md ol {
+    margin: 0 0 0.6em;
+  }
+  .wd-api-md ul,
+  .wd-api-md ol {
+    padding-left: 1.25rem;
+  }
+  .wd-api-md table {
+    display: block;
+    max-width: 100%;
+    overflow-x: auto;
+    border-collapse: collapse;
+    margin: 0.6rem 0;
+    font-size: 0.85rem;
+  }
+  .wd-api-md th,
+  .wd-api-md td {
+    padding: 0.4rem 0.75rem;
+  }
+  .wd-api-md a {
+    color: var(--wd-primary);
+  }
 </style>

package/src/components/ApiSchemaField.astro

@@ -20,6 +20,7 @@
 // component handles every level."
 import Expandable from './Expandable.astro';
 import type { SchemaRow } from '../lib/openapi-render';
+import { descriptionHtml } from '../lib/openapi-markdown';
 
 interface Props {
   rows: SchemaRow[];
@@ -33,17 +34,19 @@ interface Props {
   showRequired?: boolean;
 }
 const { rows, showRequired = true } = Astro.props as Props;
+// Descriptions are Markdown in the spec (lib/openapi-markdown.ts).
+const html = await Promise.all(rows.map((row) => descriptionHtml(row.description)));
 ---
 
 {
-  rows.map((row) => (
+  rows.map((row, i) => (
     <div class="wd-api-param">
       <div class="wd-api-param-head">
         <span class="wd-api-param-name">{row.name}</span>
         <span class="wd-api-pill wd-api-pill-type">{row.type}</span>
         {showRequired && row.required && <span class="wd-api-pill wd-api-pill-required">required</span>}
       </div>
-      {row.description && <p class="wd-api-param-desc">{row.description}</p>}
+      {html[i] && <div class="wd-api-param-desc wd-api-md" set:html={html[i]} />}
       {row.children.length > 0 && (
         <Expandable title={`${row.name} properties`} defaultOpen={false}>
           <Astro.self rows={row.children} showRequired={showRequired} />

package/src/components/Hint.astro

@@ -4,8 +4,10 @@ import { extraClasses } from './class-names';
 // (Callout, Card, Accordion, ...), which are all block-level and get
 // their own line, a Hint sits mid-sentence: `word <Hint tip="...">this
 // bit</Hint> continues`. That's why this renders a <span>, not a <div>,
-// and why its own trigger area is exactly its slotted text - no icon,
-// no padding box drawing attention to itself the way a Callout does.
+// and why its own trigger area is its slotted text plus, by default, a
+// small info icon after it - a dotted underline and that icon are the
+// whole cue, no padding box drawing attention to itself the way a Callout
+// does. `icon={false}` leaves just the underlined text.
 //
 // tip is a plain string prop (not a slot) deliberately - the tooltip
 // bubble itself needs to be one line of plain text CSS can center/
@@ -24,13 +26,20 @@ interface Props {
   headline?: string;
   cta?: string;
   href?: string;
+  /** The small info icon after the text. On unless set to false. */
+  icon?: boolean;
 }
-const { tip, headline, cta, href } = Astro.props as Props;
+const { tip, headline, cta, href, icon = true } = Astro.props as Props;
 const hasLink = Boolean(cta && href);
 ---
 
 <span class:list={["wd-hint", { "wd-hint-rich": Boolean(headline) || hasLink }, extraClasses(Astro.props)]} tabindex="0">
-  <span class="wd-hint-trigger"><slot /></span>
+  <span class="wd-hint-trigger"><slot /></span>{icon && (
+    <svg class="wd-hint-icon" viewBox="0 0 24 24" aria-hidden="true">
+      <circle cx="12" cy="12" r="9.5" />
+      <path d="M12 16.5v-5M12 8h.01" />
+    </svg>
+  )}
   <span class="wd-hint-tooltip" role="tooltip">
     {headline && <span class="wd-hint-headline">{headline}</span>}
     <span class="wd-hint-tip">{tip}</span>
@@ -52,7 +61,39 @@ const hasLink = Boolean(cta && href);
        hint here at all, since nothing about plain underlined text
        otherwise signals "hover me" the way an icon or button would. */
     cursor: help;
-    border-bottom: 1px solid var(--wd-text);
+  }
+  /* A dotted underline under the text, drawn by the font's own underline
+     rather than a border, so it follows the text across a line break and
+     sits clear of descenders. */
+  .wd-hint-trigger {
+    text-decoration-line: underline;
+    text-decoration-style: dotted;
+    text-decoration-thickness: 2px;
+    text-decoration-color: color-mix(in srgb, currentColor 55%, transparent);
+    text-underline-offset: 0.22em;
+  }
+  .wd-hint:hover .wd-hint-trigger,
+  .wd-hint:focus-visible .wd-hint-trigger {
+    text-decoration-color: currentColor;
+  }
+  /* Smaller than the text, a little clear of it, in the muted color. */
+  .wd-hint-icon {
+    display: inline-block;
+    width: 0.72em;
+    height: 0.72em;
+    margin-left: 0.22em;
+    vertical-align: -0.04em;
+    fill: none;
+    stroke: currentColor;
+    stroke-width: 2.2;
+    stroke-linecap: round;
+    stroke-linejoin: round;
+    color: var(--wd-text-muted);
+    transition: color 0.15s ease;
+  }
+  .wd-hint:hover .wd-hint-icon,
+  .wd-hint:focus-visible .wd-hint-icon {
+    color: var(--wd-text);
   }
   .wd-hint-tooltip {
     position: absolute;

package/src/components/Tooltip.astro

@@ -7,6 +7,7 @@ interface Props {
   headline?: string;
   cta?: string;
   href?: string;
+  icon?: boolean;
 }
 const props = Astro.props as Props;
 ---

package/src/lib/llms-index.ts

@@ -62,7 +62,7 @@ export async function llmsIndexFiles(): Promise<Map<string, string> | null> {
     // The .md route when it exists ([...slug].md.ts - unless `contextMenu` is off,
     // and never for an OpenAPI page, which renders from the spec), else the
     // HTML page.
-    const hasMarkdownRoute = contextMenuOptions(config.contextMenu).length > 0 && !entry.data.openapi;
+    const hasMarkdownRoute = contextMenuOptions(config.contextMenu).length > 0;
     const href = (siteUrl ?? '') + (hasMarkdownRoute ? `/${slug}.md` : slug === 'index' ? '/' : `/${slug}/`);
     let description = truncateDescription(entry.data.description);
     // Mirrors Mintlify: an OpenAPI operation page's description gets its

package/src/lib/mcp-index.ts

@@ -16,7 +16,7 @@ import {
   resolveSections,
   flattenNav,
 } from './config';
-import { markdownForAgents } from './agent-markdown.js';
+import { pageMarkdown } from './openapi-markdown';
 import { orderByNavigation } from './llms.js';
 import { writedocsTempDir } from './writedocs-temp-dir.js';
 
@@ -72,14 +72,9 @@ export async function mcpIndex(): Promise<McpIndex> {
     .map((entry) => {
       const slug = normalizeEntryId(entry.id);
       const fileId = fileIdForEntry(contentDir, packageRoot, entry);
-      let content = markdownForAgents(entry.body ?? '', {
-        file: entry.filePath ? path.resolve(packageRoot, entry.filePath) : undefined,
-        contentDir,
-        variables: config.variables,
-      }).trim();
-      // An OpenAPI operation page renders from the spec, so its source body
-      // is near-empty - name the operation, at least.
-      if (entry.data.openapi) content = [`Operation: ${entry.data.openapi}`, content].filter(Boolean).join('\n\n');
+      // An API page's source is a near-empty stub - its operation, written
+      // out from the spec, follows its own text (lib/openapi-markdown.ts).
+      const content = pageMarkdown(entry, { contentDir, packageRoot, variables: config.variables });
       return {
         slug,
         fileId,

package/src/lib/openapi-markdown.ts

@@ -0,0 +1,154 @@
+// OpenAPI operations as Markdown, both ways:
+//
+// - descriptionHtml(): a spec's `description` fields are Markdown (CommonMark,
+//   and in practice GitHub tables too) - rendered to HTML for the API page,
+//   instead of printed as literal text with its `**`, backticks and pipes.
+//   Astro's own Markdown renderer, so a description reads like any page.
+//
+// - operationMarkdown() / pageMarkdown(): an operation page written out as
+//   Markdown - method and path, description, parameters, body, responses,
+//   examples. An API page's own source is a near-empty stub (it renders from
+//   the spec), so this is what its .md copy, llms-full.txt and the MCP
+//   index serve for it, and what "Copy page" copies.
+import fs from 'node:fs';
+import path from 'node:path';
+import { createMarkdownProcessor } from '@astrojs/markdown-remark';
+import {
+  schemaRows,
+  exampleFromSchema,
+  primaryContentType,
+  findOperationFile,
+  type OpenApiOperation,
+  type SchemaRow,
+} from './openapi-render';
+import { parseOpenApiRef } from './openapi-ref.js';
+import { markdownForAgents } from './agent-markdown.js';
+
+let renderer: ReturnType<typeof createMarkdownProcessor> | null = null;
+const htmlCache = new Map<string, Promise<string>>();
+
+/** A spec description as HTML. Empty for no description. */
+export function descriptionHtml(markdown: string | null | undefined): Promise<string> {
+  const text = (markdown ?? '').trim();
+  if (!text) return Promise.resolve('');
+  let html = htmlCache.get(text);
+  if (!html) {
+    renderer ??= createMarkdownProcessor({ syntaxHighlight: false });
+    html = renderer.then((r) => r.render(text)).then((result) => result.code.trim());
+    htmlCache.set(text, html);
+  }
+  return html;
+}
+
+/** The operation a page's `openapi` frontmatter names, or null. */
+export function loadOperation(ref: string, contentDir: string): OpenApiOperation | null {
+  const parsed = parseOpenApiRef(ref);
+  if (!parsed) return null;
+  const file = findOperationFile(contentDir, parsed.method, parsed.path, parsed.spec);
+  return file ? (JSON.parse(fs.readFileSync(file, 'utf-8')) as OpenApiOperation) : null;
+}
+
+/** A description placed under a list item: every line indented to sit inside it. */
+function indented(text: string, spaces: number): string {
+  const pad = ' '.repeat(spaces);
+  return text
+    .trim()
+    .split('\n')
+    .map((line) => (line.trim() ? pad + line : ''))
+    .join('\n');
+}
+
+function fieldList(rows: SchemaRow[], depth = 0): string {
+  const pad = '  '.repeat(depth);
+  return rows
+    .map((row) => {
+      const head = `${pad}- \`${row.name}\` (${row.type}${row.required ? ', required' : ''})`;
+      const desc = row.description ? `\n${indented(row.description, pad.length + 2)}` : '';
+      const children = row.children.length ? `\n${fieldList(row.children, depth + 1)}` : '';
+      return head + desc + children;
+    })
+    .join('\n');
+}
+
+function jsonBlock(value: unknown): string {
+  return `\`\`\`json\n${JSON.stringify(value, null, 2)}\n\`\`\``;
+}
+
+/** The operation, written out as Markdown (no title - the page has its own). */
+export function operationMarkdown(op: OpenApiOperation): string {
+  const out: string[] = [];
+  out.push(`**${op.method.toUpperCase()}** \`${op.path}\``);
+  if (op.servers?.[0]?.url) out.push(`Base URL: \`${op.servers[0].url}\``);
+  if (op.description?.trim()) out.push(op.description.trim());
+  else if (op.summary?.trim()) out.push(op.summary.trim());
+
+  if (op.security?.length) {
+    const auth = op.security.map((s) => (s.scheme ? `${s.name} (${s.type}, ${s.scheme})` : s.in ? `${s.name} (${s.type} in ${s.in})` : `${s.name} (${s.type})`));
+    out.push(`## Authorization\n\n${auth.map((a) => `- ${a}`).join('\n')}`);
+  }
+
+  for (const [where, title] of [['header', 'Header parameters'], ['path', 'Path parameters'], ['query', 'Query parameters']] as const) {
+    const params = op.parameters.filter((p) => p.in === where);
+    if (!params.length) continue;
+    const list = params
+      .map((p) => {
+        const head = `- \`${p.name}\` (${p.schema?.type ?? 'string'}${p.required ? ', required' : ''})`;
+        return p.description ? `${head}\n${indented(p.description, 2)}` : head;
+      })
+      .join('\n');
+    out.push(`## ${title}\n\n${list}`);
+  }
+
+  const bodyType = primaryContentType(op.requestBody?.content);
+  const bodySchema = bodyType ? op.requestBody?.content?.[bodyType]?.schema : undefined;
+  if (bodyType && bodySchema) {
+    const rows = schemaRows(bodySchema);
+    const parts = [`## Body\n\nContent type: \`${bodyType}\``];
+    if (rows.length) parts.push(fieldList(rows));
+    const example = exampleFromSchema(bodySchema);
+    if (example !== null && example !== undefined) parts.push(`Example:\n\n${jsonBlock(example)}`);
+    out.push(parts.join('\n\n'));
+  }
+
+  const responses = Object.entries(op.responses ?? {});
+  if (responses.length) {
+    const parts = ['## Responses'];
+    for (const [status, resp] of responses) {
+      parts.push(`### ${status}${resp.description?.trim() ? `\n\n${resp.description.trim()}` : ''}`);
+      const type = primaryContentType(resp.content);
+      const schema = type ? resp.content?.[type]?.schema : undefined;
+      if (schema) {
+        const rows = schemaRows(schema);
+        if (rows.length) parts.push(fieldList(rows));
+        const example = exampleFromSchema(schema);
+        if (example !== null && example !== undefined) parts.push(`Example:\n\n${jsonBlock(example)}`);
+      }
+    }
+    out.push(parts.join('\n\n'));
+  }
+  return out.join('\n\n');
+}
+
+interface PageEntry {
+  body?: string;
+  filePath?: string;
+  data: { openapi?: string };
+}
+
+/** A page as agents read it (its .md copy, llms-full.txt, the MCP index),
+ *  without the title: its own Markdown, and for an API page the operation
+ *  after it - in the order the page shows them. */
+export function pageMarkdown(
+  entry: PageEntry,
+  { contentDir, packageRoot, variables }: { contentDir: string; packageRoot: string; variables: Record<string, string> }
+): string {
+  const own = markdownForAgents(entry.body ?? '', {
+    file: entry.filePath ? path.resolve(packageRoot, entry.filePath) : undefined,
+    contentDir,
+    variables,
+  }).trim();
+  if (!entry.data.openapi) return own;
+  const op = loadOperation(entry.data.openapi, contentDir);
+  const operation = op ? operationMarkdown(op) : `Operation: ${entry.data.openapi}`;
+  return [own, operation].filter(Boolean).join('\n\n');
+}

package/src/pages/[...slug].astro

@@ -443,7 +443,7 @@ const isCanvasMode = pageMode === "custom" || pageMode === "blank";
 // those are excluded from the .md route this menu links to in the first
 // place, which this mirrors on the UI side.
 const contextMenuItems = contextMenuOptions(config.contextMenu, { mcp: config.mcp });
-const showCopyPageMenu = contextMenuItems.length > 0 && !isCanvasMode && !entry.data.openapi;
+const showCopyPageMenu = contextMenuItems.length > 0 && !isCanvasMode;
 const siteUrl = resolveSiteUrl(config);
 
 const components = {

package/src/pages/[...slug].md.ts

@@ -4,7 +4,7 @@ import path from 'node:path';
 import type { APIRoute } from 'astro';
 import { loadDocsConfig, normalizeEntryId, findAllPages, contextMenuOptions } from '../lib/config';
 import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
-import { markdownForAgents } from '../lib/agent-markdown.js';
+import { pageMarkdown } from '../lib/openapi-markdown';
 
 // The raw-Markdown twin of [...slug].astro: every content page is also
 // reachable at the exact same slug with a literal ".md" suffix (e.g.
@@ -46,13 +46,6 @@ export async function getStaticPaths() {
   const entries: DocsEntry[] = [...pagesEntries, ...generatedDocsEntries];
 
   return entries
-    // OpenAPI operation pages (generated stubs, or hand-written pages that
-    // set `openapi:` frontmatter) render almost entirely from the spec at
-    // request time (see ApiPlayground.astro) rather than from prose in
-    // entry.body - a raw .md dump of one would be near-empty and useless
-    // 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)
@@ -81,11 +74,8 @@ export const GET: APIRoute = ({ props }) => {
   // What the page shows rather than its raw source: Mintlify's <Visibility>
   // for agents, imported snippets inlined, `variables` filled in - see
   // lib/agent-markdown.js (llms-full.txt uses the same).
-  const body = markdownForAgents(entry.body ?? '', {
-    file: entry.filePath ? path.resolve(packageRoot, entry.filePath) : undefined,
-    contentDir,
-    variables,
-  });
+  // An API page's operation is written out after its own text (lib/openapi-markdown.ts).
+  const body = pageMarkdown(entry, { contentDir, packageRoot, variables });
   const markdown = `# ${entry.data.title}\n\n${body}`;
   return new Response(markdown, {
     headers: { 'Content-Type': 'text/markdown; charset=utf-8' },

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

@@ -4,7 +4,7 @@ import path from 'node:path';
 import type { APIRoute } from 'astro';
 import { loadDocsConfig, normalizeEntryId, findAllPages, resolveSiteUrl, fileIdForEntry } from '../lib/config';
 import { writedocsTempDir } from '../lib/writedocs-temp-dir.js';
-import { markdownForAgents } from '../lib/agent-markdown.js';
+import { pageMarkdown } from '../lib/openapi-markdown';
 import { orderByNavigation } from '../lib/llms.js';
 
 // The "everything, concatenated" half of the llms.txt pair - see
@@ -43,13 +43,6 @@ export const GET: APIRoute = async () => {
   const entries: DocsEntry[] = [...pagesEntries, ...generatedDocsEntries];
 
   const unordered = entries
-    // Same exclusion [...slug].md.ts applies to its own per-page raw
-    // Markdown route, for the same reason: an OpenAPI operation page
-    // (generated stub, or a hand-written page that opts into rendering
-    // <ApiPlayground /> via `openapi:` frontmatter) renders almost
-    // entirely from the spec at request time, so entry.body alone is
-    // near-empty and not a meaningful "full content" contribution here.
-    .filter((entry) => !entry.data.openapi)
     // Same noindex exclusion llms.txt.ts applies to its own listing -
     // see that file's comment.
     .filter((entry) => !entry.data.seo?.noindex)
@@ -60,11 +53,8 @@ export const GET: APIRoute = async () => {
       // What the page shows, not its raw source: <Visibility> for agents,
       // imported snippets inlined, `variables` filled in - same as the .md
       // route (lib/agent-markdown.js).
-      const body = markdownForAgents(entry.body ?? '', {
-        file: entry.filePath ? path.resolve(packageRoot, entry.filePath) : undefined,
-        contentDir,
-        variables: config.variables,
-      });
+      // An API page's operation is written out after its own text (lib/openapi-markdown.ts).
+      const body = pageMarkdown(entry, { contentDir, packageRoot, variables: config.variables });
       // The page's own URL, so an agent can cite it.
       const url = `${siteUrl ?? ''}${slug === 'index' ? '/' : `/${slug}/`}`;
       return {