@forge-ts/gen 0.7.2 → 0.8.0

package/dist/index.js

@@ -16,33 +16,185 @@ function getAvailableTargets() {
 }
 var DEFAULT_TARGET = "mintlify";
 
-// src/adapters/mintlify.ts
-function sanitizeMdx(content) {
-  const lines = content.split("\n");
-  const result = [];
-  let insideFence = false;
-  for (const line of lines) {
-    if (insideFence) {
-      result.push(line);
-      if (/^```\s*$/.test(line)) {
-        insideFence = false;
+// src/markdown-utils.ts
+import matter from "gray-matter";
+import remarkFrontmatter from "remark-frontmatter";
+import remarkGfm from "remark-gfm";
+import remarkMdx from "remark-mdx";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+import { SKIP, visit } from "unist-util-visit";
+function createParser() {
+  return unified().use(remarkParse).use(remarkGfm).use(remarkFrontmatter, ["yaml"]);
+}
+function createMdxParser() {
+  return unified().use(remarkParse).use(remarkMdx).use(remarkGfm).use(remarkFrontmatter, ["yaml"]);
+}
+function getProtectedRangesSafe(content) {
+  try {
+    return getProtectedRangesFromTree(createMdxParser().parse(content));
+  } catch {
+    return getProtectedRangesFromTree(createParser().parse(content));
+  }
+}
+function parseFrontmatter(content) {
+  const result = matter(content);
+  return { body: result.content, data: result.data };
+}
+function stringifyWithFrontmatter(body, data) {
+  if (Object.keys(data).length === 0) return body;
+  const normalizedBody = body.startsWith("\n") ? body : `
+${body}`;
+  return matter.stringify(normalizedBody, data);
+}
+function stripFrontmatter(content) {
+  return matter(content).content;
+}
+var inlineParser = unified().use(remarkParse).use(remarkGfm);
+function parseInline(markdown) {
+  if (!markdown) return [];
+  const tree = inlineParser.parse(markdown);
+  const first = tree.children[0];
+  if (first?.type === "paragraph") {
+    return first.children;
+  }
+  return [{ type: "text", value: markdown }];
+}
+function parseBlocks(markdown) {
+  if (!markdown) return [];
+  const tree = inlineParser.parse(markdown);
+  return tree.children;
+}
+function getProtectedRangesFromTree(tree) {
+  const ranges = [];
+  visit(tree, (node) => {
+    const pos = node.position;
+    if (!pos?.start.offset || !pos?.end.offset) return;
+    if (node.type === "code" || node.type === "inlineCode" || node.type === "yaml") {
+      ranges.push({
+        start: pos.start.offset,
+        end: pos.end.offset
+      });
+      return SKIP;
+    }
+  });
+  return ranges.sort((a, b) => a.start - b.start);
+}
+function isProtected(offset, ranges) {
+  let lo = 0;
+  let hi = ranges.length - 1;
+  while (lo <= hi) {
+    const mid = lo + hi >>> 1;
+    const r = ranges[mid];
+    if (offset < r.start) {
+      hi = mid - 1;
+    } else if (offset >= r.end) {
+      lo = mid + 1;
+    } else {
+      return true;
+    }
+  }
+  return false;
+}
+function sanitizeForMdx(content) {
+  const tree = createParser().parse(content);
+  const transforms = [];
+  visit(tree, (node) => {
+    const pos = node.position;
+    if (!pos?.start.offset || !pos?.end.offset) return;
+    const start = pos.start.offset;
+    const end = pos.end.offset;
+    if (node.type === "html") {
+      const original = content.slice(start, end);
+      const commentMatch = /^<!--([\s\S]*?)-->$/.exec(original);
+      if (commentMatch) {
+        transforms.push({
+          start,
+          end,
+          replacement: `{/*${commentMatch[1]}*/}`
+        });
+      }
+      return SKIP;
+    }
+    if (node.type === "text") {
+      const original = content.slice(start, end);
+      const escaped = original.replace(/\{(?!\/\*)/g, "\\{").replace(/(?<!\*\/)\}/g, "\\}").replace(/<(\w)/g, "&lt;$1").replace(/(\w)>/g, "$1&gt;");
+      if (escaped !== original) {
+        transforms.push({ start, end, replacement: escaped });
+      }
+      return SKIP;
+    }
+    if (node.type === "code" || node.type === "inlineCode" || node.type === "yaml") {
+      return SKIP;
+    }
+  });
+  let result = content;
+  for (const t of transforms.sort((a, b) => b.start - a.start)) {
+    result = result.slice(0, t.start) + t.replacement + result.slice(t.end);
+  }
+  return result;
+}
+function findAutoSections(content) {
+  const protectedRanges = getProtectedRangesSafe(content);
+  const markers = [];
+  const patterns = [
+    { regex: /<!--\s*FORGE:AUTO-START\s+(\S+)\s*-->/g, type: "start" },
+    { regex: /<!--\s*FORGE:AUTO-END\s+(\S+)\s*-->/g, type: "end" },
+    { regex: /\{\/\*\s*FORGE:AUTO-START\s+(\S+)\s*\*\/\}/g, type: "start" },
+    { regex: /\{\/\*\s*FORGE:AUTO-END\s+(\S+)\s*\*\/\}/g, type: "end" }
+  ];
+  for (const { regex, type } of patterns) {
+    let match;
+    while ((match = regex.exec(content)) !== null) {
+      if (!isProtected(match.index, protectedRanges)) {
+        markers.push({
+          type,
+          id: match[1],
+          offset: match.index,
+          length: match[0].length
+        });
       }
-      continue;
     }
-    if (/^```/.test(line)) {
-      insideFence = true;
-      result.push(line);
-      continue;
+  }
+  markers.sort((a, b) => a.offset - b.offset);
+  const sections = /* @__PURE__ */ new Map();
+  for (let i = 0; i < markers.length; i++) {
+    const m = markers[i];
+    if (m.type !== "start") continue;
+    for (let j = i + 1; j < markers.length; j++) {
+      if (markers[j].type === "end" && markers[j].id === m.id) {
+        const sectionEnd = markers[j].offset + markers[j].length;
+        sections.set(m.id, {
+          id: m.id,
+          fullText: content.slice(m.offset, sectionEnd),
+          start: m.offset,
+          end: sectionEnd
+        });
+        break;
+      }
+    }
+  }
+  return sections;
+}
+function updateAutoSections(existing, generated) {
+  const newSections = findAutoSections(generated);
+  if (newSections.size === 0) return null;
+  const existingSections = findAutoSections(existing);
+  if (existingSections.size === 0) return null;
+  const sortedExisting = [...existingSections.entries()].sort(([, a], [, b]) => b.start - a.start);
+  let result = existing;
+  let changed = false;
+  for (const [id, existingSection] of sortedExisting) {
+    const newSection = newSections.get(id);
+    if (newSection) {
+      result = result.slice(0, existingSection.start) + newSection.fullText + result.slice(existingSection.end);
+      changed = true;
     }
-    let safe = line;
-    safe = safe.replace(/<!--([\s\S]*?)-->/g, "{/* $1 */}");
-    safe = safe.replace(/\{(?!\/\*)/g, "\\{").replace(/(?<!\*\/)\}/g, "\\}");
-    safe = safe.replace(/<(\w)/g, "&lt;$1");
-    safe = safe.replace(/(\w)>/g, "$1&gt;");
-    result.push(safe);
   }
-  return result.join("\n");
+  return changed ? result : null;
 }
+
+// src/adapters/mintlify.ts
 var styleGuide = {
   pageExtension: "mdx",
   supportsMdx: true,
@@ -120,13 +272,12 @@ function buildDocsJson(context) {
 function addMintlifyFrontmatter(page) {
   const title = String(page.frontmatter.title ?? "");
   const description = page.frontmatter.description ? String(page.frontmatter.description) : void 0;
-  const lines = ["---", `title: "${title}"`];
+  const fields = { title };
   if (description) {
-    lines.push(`description: "${description}"`);
+    fields.description = description;
   }
-  lines.push("---", "");
-  const body = page.content.replace(/^---[\s\S]*?---\n+/, "");
-  return lines.join("\n") + body;
+  const body = stripFrontmatter(page.content);
+  return stringifyWithFrontmatter(body, fields);
 }
 var mintlifyAdapter = {
   target: "mintlify",
@@ -168,7 +319,7 @@ var mintlifyAdapter = {
         }
         return line;
       }).join("\n");
-      content = sanitizeMdx(content);
+      content = sanitizeForMdx(content);
       return {
         path: page.path.replace(/\.md$/, ".mdx"),
         content,
@@ -319,16 +470,18 @@ function addDocusaurusFrontmatter(page) {
   const description = page.frontmatter.description ? String(page.frontmatter.description) : void 0;
   const sidebarLabel = page.frontmatter.sidebar_label ? String(page.frontmatter.sidebar_label) : title;
   const sidebarPosition = page.frontmatter.sidebar_position;
-  const lines = ["---", `title: "${title}"`, `sidebar_label: "${sidebarLabel}"`];
+  const fields = {
+    title,
+    sidebar_label: sidebarLabel
+  };
   if (sidebarPosition !== void 0) {
-    lines.push(`sidebar_position: ${sidebarPosition}`);
+    fields.sidebar_position = sidebarPosition;
   }
   if (description) {
-    lines.push(`description: "${description}"`);
+    fields.description = description;
   }
-  lines.push("---", "");
-  const body = page.content.replace(/^---[\s\S]*?---\n+/, "");
-  return lines.join("\n") + body;
+  const body = stripFrontmatter(page.content);
+  return stringifyWithFrontmatter(body, fields);
 }
 var docusaurusAdapter = {
   target: "docusaurus",
@@ -565,9 +718,8 @@ function addNextraFrontmatter(page) {
   if (!title) {
     return page.content;
   }
-  const lines = ["---", `title: "${title}"`, "---", ""];
-  const body = page.content.replace(/^---[\s\S]*?---\n+/, "");
-  return lines.join("\n") + body;
+  const body = stripFrontmatter(page.content);
+  return stringifyWithFrontmatter(body, { title });
 }
 var nextraAdapter = {
   target: "nextra",
@@ -720,13 +872,12 @@ function buildPackageJson3(context) {
 function addVitepressFrontmatter(page) {
   const title = String(page.frontmatter.title ?? "");
   const description = page.frontmatter.description ? String(page.frontmatter.description) : void 0;
-  const lines = ["---", `title: "${title}"`, "outline: deep"];
+  const fields = { title, outline: "deep" };
   if (description) {
-    lines.push(`description: "${description}"`);
+    fields.description = description;
   }
-  lines.push("---", "");
-  const body = page.content.replace(/^---[\s\S]*?---\n+/, "");
-  return lines.join("\n") + body;
+  const body = stripFrontmatter(page.content);
+  return stringifyWithFrontmatter(body, fields);
 }
 var vitepressAdapter = {
   target: "vitepress",
@@ -932,6 +1083,96 @@ function generateLlmsFullTxt(symbols, config) {
 
 // src/markdown.ts
 import { relative } from "path";
+
+// src/mdast-builders.ts
+import remarkFrontmatter2 from "remark-frontmatter";
+import remarkGfm2 from "remark-gfm";
+import remarkStringify from "remark-stringify";
+import { unified as unified2 } from "unified";
+var md = {
+  // Inline (phrasing) nodes
+  text: (value) => ({ type: "text", value }),
+  inlineCode: (value) => ({ type: "inlineCode", value }),
+  strong: (...children) => ({ type: "strong", children }),
+  emphasis: (...children) => ({ type: "emphasis", children }),
+  link: (url, ...children) => ({ type: "link", url, children }),
+  // Block nodes
+  heading: (depth, ...children) => ({
+    type: "heading",
+    depth,
+    children
+  }),
+  paragraph: (...children) => ({ type: "paragraph", children }),
+  code: (lang, value) => ({ type: "code", lang, value }),
+  blockquote: (...children) => ({ type: "blockquote", children }),
+  html: (value) => ({ type: "html", value }),
+  thematicBreak: () => ({ type: "thematicBreak" }),
+  // List nodes
+  listItem: (...children) => ({
+    type: "listItem",
+    spread: false,
+    children
+  }),
+  list: (items, ordered = false) => ({
+    type: "list",
+    ordered,
+    spread: false,
+    children: items
+  }),
+  // GFM table nodes
+  tableCell: (...children) => ({ type: "tableCell", children }),
+  tableRow: (...cells) => ({ type: "tableRow", children: cells }),
+  table: (align, ...rows) => ({
+    type: "table",
+    align: align ?? void 0,
+    children: rows
+  }),
+  // Root
+  root: (...children) => ({ type: "root", children })
+};
+var serializer = unified2().use(remarkGfm2).use(remarkFrontmatter2).use(remarkStringify, {
+  bullet: "-",
+  emphasis: "*",
+  strong: "*",
+  fences: true,
+  listItemIndent: "one",
+  rule: "-"
+});
+function serializeMarkdown(tree) {
+  return String(serializer.stringify(tree));
+}
+function textP(value) {
+  return md.paragraph(md.text(value));
+}
+function textListItem(value) {
+  return md.listItem(md.paragraph(md.text(value)));
+}
+function rawBlock(markdown) {
+  return md.html(markdown);
+}
+function truncate(text, maxLen = 80) {
+  if (text.length <= maxLen) return text;
+  let cutPoint = maxLen - 3;
+  const prefix = text.slice(0, cutPoint);
+  const backtickCount = (prefix.match(/`/g) || []).length;
+  if (backtickCount % 2 !== 0) {
+    const lastBacktick = prefix.lastIndexOf("`");
+    if (lastBacktick > 0) {
+      cutPoint = lastBacktick;
+    }
+  }
+  return `${text.slice(0, cutPoint).trimEnd()}...`;
+}
+function toAnchor(text) {
+  return text.toLowerCase().replace(/[^a-z0-9\s-]/g, "").trim().replace(/\s+/g, "-");
+}
+function slugLink(path) {
+  let slug = path.startsWith("./") ? path.slice(2) : path;
+  slug = slug.replace(/\.(mdx?)$/, "");
+  return `/${slug}`;
+}
+
+// src/markdown.ts
 var KIND_LABELS = {
   function: "Functions",
   class: "Classes",
@@ -950,133 +1191,131 @@ var KIND_ORDER = [
   "enum",
   "variable"
 ];
-function toAnchor(text) {
-  return text.toLowerCase().replace(/[^a-z0-9\s-]/g, "").trim().replace(/\s+/g, "-");
-}
-function buildFrontmatter(config, mdx) {
+function buildFrontmatter(config, _mdx) {
   const target = config.gen.ssgTarget;
   if (!target) return "";
-  const lines = ["---"];
+  const fields = {};
   switch (target) {
     case "docusaurus":
-      lines.push("sidebar_position: 1");
-      lines.push("title: API Reference");
+      fields.sidebar_position = 1;
+      fields.title = "API Reference";
       break;
     case "mintlify":
-      lines.push("title: API Reference");
+      fields.title = "API Reference";
       break;
     case "nextra":
-      lines.push("title: API Reference");
-      lines.push("description: Auto-generated API reference");
+      fields.title = "API Reference";
+      fields.description = "Auto-generated API reference";
       break;
     case "vitepress":
-      lines.push("title: API Reference");
-      lines.push("outline: deep");
+      fields.title = "API Reference";
+      fields.outline = "deep";
       break;
   }
-  lines.push("---");
-  if (mdx) {
-    lines.push("");
-  }
-  return `${lines.join("\n")}
-`;
+  return stringifyWithFrontmatter("", fields);
 }
 function buildMdxImports() {
   return 'import { Callout } from "@components/Callout";\n\n';
 }
-function renderDeprecation(deprecated) {
-  return `> **Deprecated**: ${deprecated}
-`;
-}
-function renderSourceLink(symbol, rootDir) {
-  const rel = relative(rootDir, symbol.filePath);
-  return `_Defined in \`${rel}:${symbol.line}\`_
-`;
-}
-function renderSymbolSection(symbol, rootDir, mdx, depth) {
-  const lines = [];
-  const hashes = "#".repeat(depth);
+function renderSymbolBlocks(symbol, rootDir, depth) {
+  const nodes = [];
   const ext = symbol.kind === "function" || symbol.kind === "method" ? "()" : "";
-  lines.push(`${hashes} \`${symbol.name}${ext}\``);
-  lines.push("");
+  const headingDepth = Math.min(depth, 6);
+  nodes.push(md.heading(headingDepth, md.inlineCode(`${symbol.name}${ext}`)));
   if (symbol.documentation?.deprecated) {
-    lines.push(renderDeprecation(symbol.documentation.deprecated));
+    nodes.push(
+      md.blockquote(
+        md.paragraph(
+          md.strong(md.text("Deprecated")),
+          md.text(": "),
+          ...parseInline(symbol.documentation.deprecated)
+        )
+      )
+    );
   }
-  lines.push(renderSourceLink(symbol, rootDir));
+  const rel = relative(rootDir, symbol.filePath);
+  nodes.push(
+    md.paragraph(md.emphasis(md.text("Defined in "), md.inlineCode(`${rel}:${symbol.line}`)))
+  );
   if (symbol.signature) {
-    lines.push("```typescript");
-    lines.push(symbol.signature);
-    lines.push("```");
-    lines.push("");
+    nodes.push(md.code("typescript", symbol.signature));
   }
   if (symbol.documentation?.summary) {
-    lines.push(symbol.documentation.summary);
-    lines.push("");
+    nodes.push(md.paragraph(...parseInline(symbol.documentation.summary)));
   }
   const params = symbol.documentation?.params ?? [];
   if (params.length > 0) {
-    lines.push("**Parameters**");
-    lines.push("");
+    nodes.push(md.paragraph(md.strong(md.text("Parameters"))));
+    const paramItems = [];
     for (const p of params) {
-      const typeStr = p.type ? ` (\`${p.type}\`)` : "";
-      lines.push(`- \`${p.name}\`${typeStr} \u2014 ${p.description}`);
+      const parts = [md.inlineCode(p.name)];
+      if (p.type) {
+        parts.push(md.text(" ("), md.inlineCode(p.type), md.text(")"));
+      }
+      parts.push(md.text(" \u2014 "), ...parseInline(p.description));
+      paramItems.push(md.listItem(md.paragraph(...parts)));
     }
-    lines.push("");
+    nodes.push(md.list(paramItems));
   }
   if (symbol.documentation?.returns) {
-    const retType = symbol.documentation.returns.type ? ` (\`${symbol.documentation.returns.type}\`)` : "";
-    lines.push(`**Returns**${retType}: ${symbol.documentation.returns.description}`);
-    lines.push("");
+    const retParts = [md.strong(md.text("Returns"))];
+    if (symbol.documentation.returns.type) {
+      retParts.push(md.text(" ("), md.inlineCode(symbol.documentation.returns.type), md.text(")"));
+    }
+    retParts.push(md.text(": "), ...parseInline(symbol.documentation.returns.description));
+    nodes.push(md.paragraph(...retParts));
   }
   const throws = symbol.documentation?.throws ?? [];
   if (throws.length > 0) {
-    lines.push("**Throws**");
-    lines.push("");
+    nodes.push(md.paragraph(md.strong(md.text("Throws"))));
+    const throwItems = [];
     for (const t of throws) {
-      const typeStr = t.type ? `\`${t.type}\` \u2014 ` : "";
-      lines.push(`- ${typeStr}${t.description}`);
+      const parts = [];
+      if (t.type) {
+        parts.push(md.inlineCode(t.type), md.text(" \u2014 "), ...parseInline(t.description));
+      } else {
+        parts.push(...parseInline(t.description));
+      }
+      throwItems.push(md.listItem(md.paragraph(...parts)));
     }
-    lines.push("");
+    nodes.push(md.list(throwItems));
   }
   const examples = symbol.documentation?.examples ?? [];
   if (examples.length > 0) {
-    lines.push("**Examples**");
-    lines.push("");
+    nodes.push(md.paragraph(md.strong(md.text("Examples"))));
     for (const ex of examples) {
-      lines.push(`\`\`\`${ex.language}`);
-      lines.push(ex.code.trim());
-      lines.push("```");
-      lines.push("");
+      nodes.push(md.code(ex.language, ex.code.trim()));
     }
   }
   const children = symbol.children ?? [];
   if (children.length > 0 && depth < 5) {
-    const childDepth = depth + 1;
     for (const child of children) {
-      lines.push(renderSymbolSection(child, rootDir, mdx, childDepth));
+      nodes.push(...renderSymbolBlocks(child, rootDir, depth + 1));
     }
   }
-  return lines.join("\n");
+  return nodes;
 }
-function buildToc(groups) {
-  const lines = [];
-  lines.push("## Table of Contents");
-  lines.push("");
+function buildTocBlocks(groups) {
+  const tocItems = [];
   for (const kind of KIND_ORDER) {
     const group = groups.get(kind);
     if (!group || group.length === 0) continue;
     const label = KIND_LABELS[kind];
     const anchor = toAnchor(label);
-    lines.push(`- [${label}](#${anchor})`);
+    const subItems = [];
     for (const symbol of group) {
       const ext = kind === "function" ? "()" : "";
       const displayName = `${symbol.name}${ext}`;
       const symAnchor = toAnchor(displayName);
-      lines.push(`  - [\`${displayName}\`](#${symAnchor})`);
+      subItems.push(
+        md.listItem(md.paragraph(md.link(`#${symAnchor}`, md.inlineCode(displayName))))
+      );
     }
+    tocItems.push(
+      md.listItem(md.paragraph(md.link(`#${anchor}`, md.text(label))), md.list(subItems))
+    );
   }
-  lines.push("");
-  return lines.join("\n");
+  return [md.heading(2, md.text("Table of Contents")), md.list(tocItems)];
 }
 function generateMarkdown(symbols, config, options = {}) {
   const mdx = options.mdx ?? false;
@@ -1088,34 +1327,40 @@ function generateMarkdown(symbols, config, options = {}) {
     list.push(symbol);
     groups.set(symbol.kind, list);
   }
-  const parts = [];
-  const frontmatter = buildFrontmatter(config, mdx);
-  if (frontmatter) {
-    parts.push(frontmatter);
-  }
-  if (mdx) {
-    parts.push(buildMdxImports());
-  }
-  parts.push("# API Reference\n");
-  parts.push(
-    `Generated by [forge-ts](https://github.com/kryptobaseddev/forge-ts) from \`${config.rootDir}\`.
-`
+  const nodes = [];
+  nodes.push(md.heading(1, md.text("API Reference")));
+  nodes.push(
+    md.paragraph(
+      md.text("Generated by "),
+      md.link("https://github.com/kryptobaseddev/forge-ts", md.text("forge-ts")),
+      md.text(" from "),
+      md.inlineCode(config.rootDir),
+      md.text(".")
+    )
   );
   if (topLevel.length > 0) {
-    parts.push(buildToc(groups));
+    nodes.push(...buildTocBlocks(groups));
   }
   for (const kind of KIND_ORDER) {
     const group = groups.get(kind);
     if (!group || group.length === 0) continue;
     const label = KIND_LABELS[kind];
-    parts.push(`## ${label}
-`);
+    nodes.push(md.heading(2, md.text(label)));
     for (const symbol of group) {
-      parts.push(renderSymbolSection(symbol, config.rootDir, mdx, 3));
-      parts.push("");
+      nodes.push(...renderSymbolBlocks(symbol, config.rootDir, 3));
     }
   }
-  return `${parts.join("\n").replace(/\n{3,}/g, "\n\n").trimEnd()}
+  const body = serializeMarkdown(md.root(...nodes));
+  const parts = [];
+  const frontmatter = buildFrontmatter(config, mdx);
+  if (frontmatter) {
+    parts.push(frontmatter);
+  }
+  if (mdx) {
+    parts.push(buildMdxImports());
+  }
+  parts.push(body);
+  return `${parts.join("").trimEnd()}
 `;
 }
 
@@ -1124,59 +1369,67 @@ import { existsSync } from "fs";
 import { readFile, writeFile } from "fs/promises";
 var SECTION_START = "<!-- forge-ts:start -->";
 var SECTION_END = "<!-- forge-ts:end -->";
-function tableSignature(symbol) {
-  if (!symbol.signature) {
-    const ext = symbol.kind === "function" ? "()" : "";
-    return `\`${symbol.name}${ext}\``;
-  }
-  const sig = symbol.signature.length > 60 ? `${symbol.signature.slice(0, 57)}...` : symbol.signature;
-  return `\`${sig}\``;
-}
-function renderFirstExample(symbol) {
-  const examples = symbol.documentation?.examples ?? [];
-  if (examples.length === 0) return "";
-  const ex = examples[0];
-  return ["", `\`\`\`${ex.language}`, ex.code.trim(), "```"].join("\n");
-}
-function buildApiTable(symbols, includeExamples) {
-  const lines = ["| Symbol | Kind | Description |", "|--------|------|-------------|"];
+function buildApiBlocks(symbols, includeExamples) {
+  const nodes = [];
+  const headerRow = md.tableRow(
+    md.tableCell(md.text("Symbol")),
+    md.tableCell(md.text("Kind")),
+    md.tableCell(md.text("Description"))
+  );
+  const dataRows = [];
   for (const s of symbols) {
-    const sig = tableSignature(s);
+    let sigText;
+    if (!s.signature) {
+      const ext = s.kind === "function" ? "()" : "";
+      sigText = `${s.name}${ext}`;
+    } else {
+      sigText = s.signature.length > 60 ? `${s.signature.slice(0, 57)}...` : s.signature;
+    }
     const summary = s.documentation?.summary ?? "";
-    lines.push(`| ${sig} | ${s.kind} | ${summary} |`);
+    dataRows.push(
+      md.tableRow(
+        md.tableCell(md.inlineCode(sigText)),
+        md.tableCell(md.text(s.kind)),
+        md.tableCell(...summary ? parseInline(summary) : [md.text("")])
+      )
+    );
   }
+  nodes.push(md.table(null, headerRow, ...dataRows));
   if (includeExamples) {
     const withExamples = symbols.filter((s) => (s.documentation?.examples ?? []).length > 0);
     if (withExamples.length > 0) {
-      lines.push("");
-      lines.push("### Examples");
+      nodes.push(md.heading(3, md.text("Examples")));
       for (const s of withExamples) {
-        lines.push("");
         const ext = s.kind === "function" ? "()" : "";
-        lines.push(`#### \`${s.name}${ext}\``);
-        lines.push(renderFirstExample(s));
+        nodes.push(md.heading(4, md.inlineCode(`${s.name}${ext}`)));
+        const examples = s.documentation?.examples ?? [];
+        const ex = examples[0];
+        nodes.push(md.code(ex.language, ex.code.trim()));
       }
     }
   }
-  return lines;
+  return nodes;
 }
 async function syncReadme(readmePath, symbols, options = {}) {
   const exported = symbols.filter((s) => s.exported);
   if (exported.length === 0) return false;
   const badge = options.badge ?? false;
   const includeExamples = options.includeExamples ?? false;
-  const innerLines = [];
-  innerLines.push("## API Overview");
-  innerLines.push("");
+  const innerNodes = [];
+  innerNodes.push(md.heading(2, md.text("API Overview")));
   if (badge) {
-    innerLines.push(
-      "[![Documented with forge-ts](https://img.shields.io/badge/docs-forge--ts-blue)](https://github.com/forge-ts/forge-ts)"
+    innerNodes.push(
+      rawBlock(
+        "[![Documented with forge-ts](https://img.shields.io/badge/docs-forge--ts-blue)](https://github.com/forge-ts/forge-ts)"
+      )
     );
-    innerLines.push("");
   }
-  innerLines.push(...buildApiTable(exported, includeExamples));
-  const summaryLines = [SECTION_START, "", ...innerLines, "", SECTION_END];
-  const injection = summaryLines.join("\n");
+  innerNodes.push(...buildApiBlocks(exported, includeExamples));
+  const innerMd = serializeMarkdown(md.root(...innerNodes));
+  const injection = `${SECTION_START}
+
+${innerMd}
+${SECTION_END}`;
   let existing = existsSync(readmePath) ? await readFile(readmePath, "utf8") : "";
   const startIdx = existing.indexOf(SECTION_START);
   const endIdx = existing.indexOf(SECTION_END);
@@ -1194,25 +1447,12 @@ ${injection}
 
 // src/site-generator.ts
 import { basename, relative as relative2 } from "path";
-function toAnchor2(text) {
-  return text.toLowerCase().replace(/[^a-z0-9\s-]/g, "").trim().replace(/\s+/g, "-");
-}
-function escapePipe(text) {
-  return text.replace(/\|/g, "\\|");
-}
 function escapeMdx(text) {
   return text.replace(/\{/g, "\\{").replace(/\}/g, "\\}").replace(/<(\w)/g, "&lt;$1").replace(/(\w)>/g, "$1&gt;");
 }
 function serializeFrontmatter(fields) {
   if (Object.keys(fields).length === 0) return "";
-  const lines = ["---"];
-  for (const [key, value] of Object.entries(fields)) {
-    lines.push(`${key}: ${value}`);
-  }
-  lines.push("---");
-  return `${lines.join("\n")}
-
-`;
+  return stringifyWithFrontmatter("", fields);
 }
 function buildFrontmatterFields(title, description, ssgTarget, sidebarPosition) {
   if (!ssgTarget) return {};
@@ -1250,15 +1490,6 @@ function buildFrontmatterFields(title, description, ssgTarget, sidebarPosition)
       return {};
   }
 }
-function slugLink(path) {
-  let slug = path.startsWith("./") ? path.slice(2) : path;
-  slug = slug.replace(/\.(mdx?)$/, "");
-  return `/${slug}`;
-}
-function truncate(text, maxLen = 80) {
-  if (text.length <= maxLen) return text;
-  return `${text.slice(0, maxLen - 3)}...`;
-}
 function groupSymbolsByPackage(symbols, rootDir) {
   const result = /* @__PURE__ */ new Map();
   for (const symbol of symbols) {
@@ -1274,33 +1505,46 @@ function groupSymbolsByPackage(symbols, rootDir) {
 var TYPE_KINDS = /* @__PURE__ */ new Set(["interface", "type", "enum"]);
 var FUNCTION_KINDS = /* @__PURE__ */ new Set(["function", "class"]);
 function renderProjectIndexPage(symbolsByPackage, options) {
-  const lines = [];
+  const nodes = [];
   if (options.projectDescription) {
-    lines.push(`**${options.projectName}** \u2014 ${options.projectDescription}`);
+    nodes.push(
+      md.paragraph(
+        md.strong(md.text(options.projectName)),
+        md.text(` \u2014 ${options.projectDescription}`)
+      )
+    );
   } else {
-    lines.push(
-      `**${options.projectName}** is a TypeScript documentation toolkit that performs a single AST traversal of your project and produces API docs, OpenAPI specs, executable doctests, and AI context files in one pass.`
+    nodes.push(
+      md.paragraph(
+        md.strong(md.text(options.projectName)),
+        md.text(
+          " is a TypeScript documentation toolkit that performs a single AST traversal of your project and produces API docs, OpenAPI specs, executable doctests, and AI context files in one pass."
+        )
+      )
     );
   }
-  lines.push("");
-  lines.push("## Features");
-  lines.push("");
+  nodes.push(md.heading(2, md.text("Features")));
   const pkgCount = symbolsByPackage.size;
+  const featureItems = [];
   if (pkgCount > 1) {
-    lines.push(`- ${pkgCount} packages with full TypeScript support`);
+    featureItems.push(textListItem(`${pkgCount} packages with full TypeScript support`));
   } else {
-    lines.push("- Full TypeScript support with TSDoc extraction");
-  }
-  lines.push("- Auto-generated API reference from source code");
-  lines.push("- Executable `@example` blocks as doctests");
-  lines.push("- AI-ready context files from a single build pass");
-  lines.push("");
-  lines.push("## Installation");
-  lines.push("");
-  lines.push("```bash");
-  lines.push(`npm install -D ${options.packageName ?? "@forge-ts/cli"}`);
-  lines.push("```");
-  lines.push("");
+    featureItems.push(textListItem("Full TypeScript support with TSDoc extraction"));
+  }
+  featureItems.push(textListItem("Auto-generated API reference from source code"));
+  featureItems.push(
+    md.listItem(
+      md.paragraph(
+        md.text("Executable "),
+        md.inlineCode("@example"),
+        md.text(" blocks as doctests")
+      )
+    )
+  );
+  featureItems.push(textListItem("AI-ready context files from a single build pass"));
+  nodes.push(md.list(featureItems));
+  nodes.push(md.heading(2, md.text("Installation")));
+  nodes.push(md.code("bash", `npm install -D ${options.packageName ?? "@forge-ts/cli"}`));
   let firstExample;
   outer: for (const [, symbols] of symbolsByPackage) {
     for (const s of symbols) {
@@ -1313,36 +1557,53 @@ function renderProjectIndexPage(symbolsByPackage, options) {
     }
   }
   if (firstExample) {
-    lines.push("## Quick Example");
-    lines.push("");
-    lines.push(`\`\`\`${firstExample.language || "typescript"}`);
-    lines.push(firstExample.code.trim());
-    lines.push("```");
-    lines.push("");
+    nodes.push(md.heading(2, md.text("Quick Example")));
+    nodes.push(md.code(firstExample.language || "typescript", firstExample.code.trim()));
   }
   if (symbolsByPackage.size > 0) {
-    lines.push("## Packages");
-    lines.push("");
-    lines.push("| Package | Description |");
-    lines.push("|---------|-------------|");
+    nodes.push(md.heading(2, md.text("Packages")));
+    const headerRow = md.tableRow(
+      md.tableCell(md.text("Package")),
+      md.tableCell(md.text("Description"))
+    );
+    const dataRows = [];
     for (const [pkgName, symbols] of symbolsByPackage) {
       const pkgDoc = symbols.map((s) => s.documentation?.tags?.packageDocumentation?.[0]).find(Boolean);
       const exported = symbols.filter(
         (s) => s.exported && s.kind !== "method" && s.kind !== "property"
       );
       const rawDesc = pkgDoc ?? `${exported.length} exported symbol(s).`;
-      const desc = escapePipe(truncate(rawDesc));
-      const link = `[\`${pkgName}\`](${slugLink(`packages/${pkgName}/index`)})`;
-      lines.push(`| ${link} | ${desc} |`);
+      const desc = truncate(rawDesc);
+      dataRows.push(
+        md.tableRow(
+          md.tableCell(md.link(slugLink(`packages/${pkgName}/index`), md.inlineCode(pkgName))),
+          md.tableCell(md.text(desc))
+        )
+      );
     }
-    lines.push("");
-  }
-  lines.push("## Next Steps");
-  lines.push("");
-  lines.push(`- [Getting Started](/getting-started) \u2014 Step-by-step guide`);
-  lines.push(`- [API Reference](/packages) \u2014 Full API documentation`);
-  lines.push(`- [Concepts](/concepts) \u2014 How it works`);
-  return lines.join("\n");
+    nodes.push(md.table(null, headerRow, ...dataRows));
+  }
+  nodes.push(md.heading(2, md.text("Next Steps")));
+  nodes.push(
+    md.list([
+      md.listItem(
+        md.paragraph(
+          md.link("/getting-started", md.text("Getting Started")),
+          md.text(" \u2014 Step-by-step guide")
+        )
+      ),
+      md.listItem(
+        md.paragraph(
+          md.link("/packages", md.text("API Reference")),
+          md.text(" \u2014 Full API documentation")
+        )
+      ),
+      md.listItem(
+        md.paragraph(md.link("/concepts", md.text("Concepts")), md.text(" \u2014 How it works"))
+      )
+    ])
+  );
+  return serializeMarkdown(md.root(...nodes));
 }
 function renderGettingStartedPage(symbolsByPackage, options) {
   let firstExample;
@@ -1356,126 +1617,143 @@ function renderGettingStartedPage(symbolsByPackage, options) {
       }
     }
   }
-  const lines = [];
-  lines.push(`Get up and running with **${options.projectName}** in minutes.`);
+  const nodes = [];
+  nodes.push(
+    md.paragraph(
+      md.text("Get up and running with "),
+      md.strong(md.text(options.projectName)),
+      md.text(" in minutes.")
+    )
+  );
   if (options.projectDescription) {
-    lines.push("");
-    lines.push(options.projectDescription);
-  }
-  lines.push("");
-  lines.push("## Step 1: Install");
-  lines.push("");
-  lines.push("```bash");
-  lines.push(`npm install -D ${options.packageName ?? "@forge-ts/cli"}`);
-  lines.push("```");
-  lines.push("");
-  lines.push("## Step 2: Add TSDoc to your code");
-  lines.push("");
-  lines.push("Add TSDoc comments to your exported functions and types:");
-  lines.push("");
-  lines.push("```typescript");
-  lines.push("/**");
-  lines.push(" * Adds two numbers together.");
-  lines.push(" * @param a - First number");
-  lines.push(" * @param b - Second number");
-  lines.push(" * @returns The sum of a and b");
-  lines.push(" * @example");
-  lines.push(" * ```typescript");
-  lines.push(" * const result = add(1, 2); // => 3");
-  lines.push(" * ```");
-  lines.push(" */");
-  lines.push("export function add(a: number, b: number): number {");
-  lines.push("  return a + b;");
-  lines.push("}");
-  lines.push("```");
-  lines.push("");
-  lines.push("## Step 3: Run forge-ts check");
-  lines.push("");
-  lines.push("Lint your TSDoc coverage before generating docs:");
-  lines.push("");
-  lines.push("```bash");
-  lines.push("npx forge-ts check");
-  lines.push("```");
-  lines.push("");
-  lines.push("Expected output:");
-  lines.push("");
-  lines.push("```");
-  lines.push("forge-ts: checking TSDoc coverage...");
-  lines.push("  \u2713 All public symbols documented");
-  lines.push("```");
-  lines.push("");
-  lines.push("## Step 4: Generate docs");
-  lines.push("");
-  lines.push("Build your documentation site:");
-  lines.push("");
-  lines.push("```bash");
-  lines.push("npx forge-ts build");
-  lines.push("```");
-  lines.push("");
+    nodes.push(md.paragraph(...parseInline(options.projectDescription)));
+  }
+  nodes.push(md.heading(2, md.text("Step 1: Install")));
+  nodes.push(md.code("bash", `npm install -D ${options.packageName ?? "@forge-ts/cli"}`));
+  nodes.push(md.heading(2, md.text("Step 2: Add TSDoc to your code")));
+  nodes.push(textP("Add TSDoc comments to your exported functions and types:"));
+  nodes.push(
+    md.code(
+      "typescript",
+      [
+        "/**",
+        " * Adds two numbers together.",
+        " * @param a - First number",
+        " * @param b - Second number",
+        " * @returns The sum of a and b",
+        " * @example",
+        " * ```typescript",
+        " * const result = add(1, 2); // => 3",
+        " * ```",
+        " */",
+        "export function add(a: number, b: number): number {",
+        "  return a + b;",
+        "}"
+      ].join("\n")
+    )
+  );
+  nodes.push(md.heading(2, md.text("Step 3: Run forge-ts check")));
+  nodes.push(textP("Lint your TSDoc coverage before generating docs:"));
+  nodes.push(md.code("bash", "npx forge-ts check"));
+  nodes.push(textP("Expected output:"));
+  nodes.push(
+    md.code(
+      "",
+      ["forge-ts: checking TSDoc coverage...", "  \u2713 All public symbols documented"].join("\n")
+    )
+  );
+  nodes.push(md.heading(2, md.text("Step 4: Generate docs")));
+  nodes.push(textP("Build your documentation site:"));
+  nodes.push(md.code("bash", "npx forge-ts build"));
   if (firstExample) {
-    lines.push("Your code examples become live documentation:");
-    lines.push("");
-    lines.push(`\`\`\`${firstExample.language || "typescript"}`);
-    lines.push(firstExample.code.trim());
-    lines.push("```");
-    lines.push("");
-  }
-  lines.push("## What's Next?");
-  lines.push("");
-  lines.push("- [Concepts](/concepts) \u2014 Understand how forge-ts works");
-  lines.push("- [API Reference](/packages) \u2014 Full API documentation");
-  lines.push("- [Guides](/guides) \u2014 Practical how-to guides");
-  return lines.join("\n");
+    nodes.push(textP("Your code examples become live documentation:"));
+    nodes.push(md.code(firstExample.language || "typescript", firstExample.code.trim()));
+  }
+  nodes.push(md.heading(2, md.text("What's Next?")));
+  nodes.push(
+    md.list([
+      md.listItem(
+        md.paragraph(
+          md.link("/concepts", md.text("Concepts")),
+          md.text(" \u2014 Understand how forge-ts works")
+        )
+      ),
+      md.listItem(
+        md.paragraph(
+          md.link("/packages", md.text("API Reference")),
+          md.text(" \u2014 Full API documentation")
+        )
+      ),
+      md.listItem(
+        md.paragraph(md.link("/guides", md.text("Guides")), md.text(" \u2014 Practical how-to guides"))
+      )
+    ])
+  );
+  return serializeMarkdown(md.root(...nodes));
 }
 function renderConceptsPage(symbolsByPackage, options) {
-  const lines = [];
-  lines.push(`This page explains the core concepts behind **${options.projectName}**.`);
-  lines.push("");
-  lines.push(
-    "> This is a stub page. Edit this file to add your project's conceptual documentation."
+  const nodes = [];
+  nodes.push(
+    md.paragraph(
+      md.text("This page explains the core concepts behind "),
+      md.strong(md.text(options.projectName)),
+      md.text(".")
+    )
+  );
+  nodes.push(
+    md.blockquote(
+      textP("This is a stub page. Edit this file to add your project's conceptual documentation."),
+      textP("Auto-generated sections below (inside FORGE:AUTO markers) update on every build.")
+    )
   );
-  lines.push("> Auto-generated sections below (inside FORGE:AUTO markers) update on every build.");
-  lines.push("");
   const pkgDoc = [...symbolsByPackage.values()].flatMap((syms) => syms.map((s) => s.documentation?.tags?.packageDocumentation?.[0])).find(Boolean);
-  lines.push("<!-- FORGE:AUTO-START how-it-works -->");
-  lines.push("## How It Works");
-  lines.push("");
+  nodes.push(md.html("<!-- FORGE:AUTO-START how-it-works -->"));
+  nodes.push(md.heading(2, md.text("How It Works")));
   if (pkgDoc) {
-    lines.push(pkgDoc);
+    nodes.push(md.paragraph(...parseInline(pkgDoc)));
   } else {
-    lines.push(
-      `${options.projectName} processes your TypeScript source with a single AST traversal, extracting TSDoc comments and type information to generate documentation.`
+    nodes.push(
+      textP(
+        `${options.projectName} processes your TypeScript source with a single AST traversal, extracting TSDoc comments and type information to generate documentation.`
+      )
     );
   }
-  lines.push("");
-  lines.push("<!-- FORGE:AUTO-END how-it-works -->");
-  lines.push("");
+  nodes.push(md.html("<!-- FORGE:AUTO-END how-it-works -->"));
   const allTypeSymbols = [...symbolsByPackage.values()].flat().filter((s) => s.exported && TYPE_KINDS.has(s.kind));
   if (allTypeSymbols.length > 0) {
-    lines.push("<!-- FORGE:AUTO-START key-abstractions -->");
-    lines.push("## Key Abstractions");
-    lines.push("");
+    nodes.push(md.html("<!-- FORGE:AUTO-START key-abstractions -->"));
+    nodes.push(md.heading(2, md.text("Key Abstractions")));
+    const items = [];
     for (const s of allTypeSymbols) {
       const desc = s.documentation?.summary ?? `The \`${s.name}\` ${s.kind}.`;
-      lines.push(`- **\`${s.name}\`** \u2014 ${desc}`);
+      items.push(
+        md.listItem(
+          md.paragraph(md.strong(md.inlineCode(s.name)), md.text(" \u2014 "), ...parseInline(desc))
+        )
+      );
     }
-    lines.push("");
-    lines.push("<!-- FORGE:AUTO-END key-abstractions -->");
-    lines.push("");
+    nodes.push(md.list(items));
+    nodes.push(md.html("<!-- FORGE:AUTO-END key-abstractions -->"));
   }
-  return lines.join("\n");
+  return serializeMarkdown(md.root(...nodes));
 }
 function renderGuidesIndexPage() {
-  return [
-    "Practical how-to guides for common tasks.",
-    "",
-    "> Add your guides to the `guides/` directory. Each `.md` or `.mdx` file will appear here automatically.",
-    "",
-    "## Getting Things Done",
-    "",
-    "Guides will appear here as you add them. Start by creating a file like `guides/my-guide.md`.",
-    ""
-  ].join("\n");
+  const nodes = [];
+  nodes.push(textP("Practical how-to guides for common tasks."));
+  nodes.push(
+    md.blockquote(
+      textP(
+        "Add your guides to the `guides/` directory. Each `.md` or `.mdx` file will appear here automatically."
+      )
+    )
+  );
+  nodes.push(md.heading(2, md.text("Getting Things Done")));
+  nodes.push(
+    textP(
+      "Guides will appear here as you add them. Start by creating a file like `guides/my-guide.md`."
+    )
+  );
+  return serializeMarkdown(md.root(...nodes));
 }
 function renderApiIndexPage(pkgName, symbols) {
   const exported = symbols.filter(
@@ -1484,45 +1762,57 @@ function renderApiIndexPage(pkgName, symbols) {
   const functions = exported.filter((s) => FUNCTION_KINDS.has(s.kind));
   const types = exported.filter((s) => TYPE_KINDS.has(s.kind));
   const others = exported.filter((s) => !FUNCTION_KINDS.has(s.kind) && !TYPE_KINDS.has(s.kind));
-  const lines = [];
+  const nodes = [];
   const pkgDoc = symbols.map((s) => s.documentation?.tags?.packageDocumentation?.[0]).find(Boolean);
   if (pkgDoc) {
-    lines.push(pkgDoc);
-    lines.push("");
+    nodes.push(md.paragraph(...parseInline(pkgDoc)));
   } else {
-    lines.push(`API reference for the \`${pkgName}\` package.`);
-    lines.push("");
+    nodes.push(
+      md.paragraph(md.text("API reference for the "), md.inlineCode(pkgName), md.text(" package."))
+    );
   }
   const renderGroup = (group, heading, pathSuffix) => {
     if (group.length === 0) return;
-    lines.push(`## ${heading}`);
-    lines.push("");
-    lines.push("| Symbol | Kind | Description |");
-    lines.push("|--------|------|-------------|");
+    nodes.push(md.heading(2, md.text(heading)));
+    const headerRow = md.tableRow(
+      md.tableCell(md.text("Symbol")),
+      md.tableCell(md.text("Kind")),
+      md.tableCell(md.text("Description"))
+    );
+    const dataRows = [];
     for (const s of group) {
       const ext = s.kind === "function" ? "()" : "";
-      const anchor = toAnchor2(`${s.name}${ext}`);
-      const link = `[\`${s.name}${ext}\`](${slugLink(`packages/${pkgName}/${pathSuffix}`)}#${anchor})`;
+      const anchor = toAnchor(`${s.name}${ext}`);
       const rawSummary = s.documentation?.summary ?? "";
-      const summary = escapePipe(truncate(rawSummary));
-      lines.push(`| ${link} | ${s.kind} | ${summary} |`);
+      const summary = truncate(rawSummary);
+      dataRows.push(
+        md.tableRow(
+          md.tableCell(
+            md.link(
+              `${slugLink(`packages/${pkgName}/${pathSuffix}`)}#${anchor}`,
+              md.inlineCode(`${s.name}${ext}`)
+            )
+          ),
+          md.tableCell(md.text(s.kind)),
+          md.tableCell(...parseInline(summary))
+        )
+      );
     }
-    lines.push("");
+    nodes.push(md.table(null, headerRow, ...dataRows));
   };
   renderGroup(functions, "Functions & Classes", "api/functions");
   renderGroup(types, "Types & Interfaces", "api/types");
   renderGroup(others, "Other Exports", "api/functions");
-  return lines.join("\n");
+  return serializeMarkdown(md.root(...nodes));
 }
 function renderPackageOverviewPage(packageName, symbols, _options) {
   const exported = symbols.filter(
     (s) => s.exported && s.kind !== "method" && s.kind !== "property"
   );
   const pkgDoc = symbols.map((s) => s.documentation?.tags?.packageDocumentation?.[0]).find(Boolean);
-  const lines = [];
+  const nodes = [];
   if (pkgDoc) {
-    lines.push(pkgDoc);
-    lines.push("");
+    nodes.push(md.paragraph(...parseInline(pkgDoc)));
   }
   if (exported.length > 0) {
     const functions = exported.filter((s) => FUNCTION_KINDS.has(s.kind));
@@ -1530,96 +1820,127 @@ function renderPackageOverviewPage(packageName, symbols, _options) {
     const others = exported.filter((s) => !FUNCTION_KINDS.has(s.kind) && !TYPE_KINDS.has(s.kind));
     const renderGroup = (group, heading) => {
       if (group.length === 0) return;
-      lines.push(`## ${heading}`);
-      lines.push("");
-      lines.push("| Symbol | Kind | Description |");
-      lines.push("|--------|------|-------------|");
+      nodes.push(md.heading(2, md.text(heading)));
+      const headerRow = md.tableRow(
+        md.tableCell(md.text("Symbol")),
+        md.tableCell(md.text("Kind")),
+        md.tableCell(md.text("Description"))
+      );
+      const dataRows = [];
       for (const s of group) {
         const ext = s.kind === "function" ? "()" : "";
-        const name = `[\`${s.name}${ext}\`](${slugLink(`packages/${packageName}/api/index`)}#${toAnchor2(`${s.name}${ext}`)})`;
+        const anchor = toAnchor(`${s.name}${ext}`);
         const rawSummary = s.documentation?.summary ?? "";
-        const summary = escapePipe(truncate(rawSummary));
-        lines.push(`| ${name} | ${s.kind} | ${summary} |`);
+        const summary = truncate(rawSummary);
+        dataRows.push(
+          md.tableRow(
+            md.tableCell(
+              md.link(
+                `${slugLink(`packages/${packageName}/api/index`)}#${anchor}`,
+                md.inlineCode(`${s.name}${ext}`)
+              )
+            ),
+            md.tableCell(md.text(s.kind)),
+            md.tableCell(...parseInline(summary))
+          )
+        );
       }
-      lines.push("");
+      nodes.push(md.table(null, headerRow, ...dataRows));
     };
     renderGroup(functions, "Functions & Classes");
     renderGroup(types, "Types & Interfaces");
     renderGroup(others, "Other Exports");
   }
-  return lines.join("\n");
+  return serializeMarkdown(md.root(...nodes));
 }
 function renderTypesPage(packageName, symbols, _options) {
   const typeSymbols = symbols.filter((s) => s.exported && TYPE_KINDS.has(s.kind));
-  const lines = [];
-  lines.push("Type contracts exported by this package: interfaces, type aliases, and enums.");
-  lines.push("");
+  const nodes = [];
+  nodes.push(
+    textP("Type contracts exported by this package: interfaces, type aliases, and enums.")
+  );
   for (const s of typeSymbols) {
-    lines.push(`## ${s.name}`);
-    lines.push("");
+    nodes.push(md.heading(2, md.text(s.name)));
     if (s.documentation?.deprecated) {
-      lines.push(`> **Deprecated**: ${s.documentation.deprecated}`);
-      lines.push("");
+      nodes.push(
+        md.blockquote(
+          md.paragraph(
+            md.strong(md.text("Deprecated")),
+            md.text(": "),
+            ...parseInline(s.documentation.deprecated)
+          )
+        )
+      );
     }
     if (s.documentation?.summary) {
-      lines.push(s.documentation.summary);
-      lines.push("");
+      nodes.push(md.paragraph(...parseInline(s.documentation.summary)));
     }
     if (s.signature && s.kind !== "interface") {
-      lines.push("```typescript");
-      lines.push(s.signature);
-      lines.push("```");
-      lines.push("");
+      nodes.push(md.code("typescript", s.signature));
     }
     const children = (s.children ?? []).filter((c) => c.kind === "property" || c.kind === "method");
     if (children.length > 0) {
-      lines.push("| Property | Type | Required | Description |");
-      lines.push("|----------|------|----------|-------------|");
+      const headerRow = md.tableRow(
+        md.tableCell(md.text("Property")),
+        md.tableCell(md.text("Type")),
+        md.tableCell(md.text("Required")),
+        md.tableCell(md.text("Description"))
+      );
+      const dataRows = [];
       for (const child of children) {
-        const name = `\`${child.name}\``;
-        const type = child.signature ? `\`${escapePipe(child.signature)}\`` : "\u2014";
+        const typePhrasing = child.signature ? md.inlineCode(child.signature) : md.text("\u2014");
         const optional = child.signature?.includes("?") || child.signature?.includes("undefined") ? "No" : "Yes";
-        const description = escapePipe(child.documentation?.summary || child.name);
-        lines.push(`| ${name} | ${type} | ${optional} | ${description} |`);
+        const description = child.documentation?.summary || child.name;
+        dataRows.push(
+          md.tableRow(
+            md.tableCell(md.inlineCode(child.name)),
+            md.tableCell(typePhrasing),
+            md.tableCell(md.text(optional)),
+            md.tableCell(...parseInline(description))
+          )
+        );
       }
-      lines.push("");
+      nodes.push(md.table(null, headerRow, ...dataRows));
     }
   }
   void packageName;
-  return lines.join("\n");
+  return serializeMarkdown(md.root(...nodes));
 }
 function renderFunctionsPage(packageName, symbols, _options) {
   const fnSymbols = symbols.filter((s) => s.exported && FUNCTION_KINDS.has(s.kind));
-  const lines = [];
-  lines.push("Functions and classes exported by this package.");
-  lines.push("");
+  const nodes = [];
+  nodes.push(textP("Functions and classes exported by this package."));
   for (const s of fnSymbols) {
     const paramSig = s.kind === "function" && s.documentation?.params ? s.documentation.params.map((p) => p.name).join(", ") : "";
     const heading = s.kind === "function" ? `${s.name}(${paramSig})` : s.name;
-    lines.push(`## ${heading}`);
-    lines.push("");
+    nodes.push(md.heading(2, md.text(heading)));
     if (s.documentation?.deprecated) {
-      lines.push(`> **Deprecated**: ${s.documentation.deprecated}`);
-      lines.push("");
+      nodes.push(
+        md.blockquote(
+          md.paragraph(
+            md.strong(md.text("Deprecated")),
+            md.text(": "),
+            ...parseInline(s.documentation.deprecated)
+          )
+        )
+      );
     }
     if (s.documentation?.summary) {
-      lines.push(s.documentation.summary);
-      lines.push("");
+      nodes.push(md.paragraph(...parseInline(s.documentation.summary)));
     }
     if (s.signature) {
-      lines.push("**Signature**");
-      lines.push("");
-      lines.push("```typescript");
-      lines.push(s.signature);
-      lines.push("```");
-      lines.push("");
+      nodes.push(md.paragraph(md.strong(md.text("Signature"))));
+      nodes.push(md.code("typescript", s.signature));
     }
     const params = s.documentation?.params ?? [];
     if (params.length > 0) {
-      lines.push("**Parameters**");
-      lines.push("");
-      lines.push("| Name | Type | Description |");
-      lines.push("|------|------|-------------|");
+      nodes.push(md.paragraph(md.strong(md.text("Parameters"))));
+      const headerRow = md.tableRow(
+        md.tableCell(md.text("Name")),
+        md.tableCell(md.text("Type")),
+        md.tableCell(md.text("Description"))
+      );
+      const dataRows = [];
       for (const p of params) {
         let resolvedType = p.type;
         if (!resolvedType && s.signature) {
@@ -1628,183 +1949,254 @@ function renderFunctionsPage(packageName, symbols, _options) {
             resolvedType = typeMatch[1].trim();
           }
         }
-        const type = resolvedType ? `\`${escapePipe(resolvedType)}\`` : "\u2014";
-        lines.push(`| \`${p.name}\` | ${type} | ${escapePipe(p.description)} |`);
+        const typePhrasing = resolvedType ? md.inlineCode(resolvedType) : md.text("\u2014");
+        dataRows.push(
+          md.tableRow(
+            md.tableCell(md.inlineCode(p.name)),
+            md.tableCell(typePhrasing),
+            md.tableCell(...parseInline(p.description))
+          )
+        );
       }
-      lines.push("");
+      nodes.push(md.table(null, headerRow, ...dataRows));
     }
     if (s.documentation?.returns) {
-      const retType = s.documentation.returns.type ? ` \`${s.documentation.returns.type}\`` : "";
-      lines.push(`**Returns**${retType} \u2014 ${s.documentation.returns.description}`);
-      lines.push("");
+      const retParts = [md.strong(md.text("Returns"))];
+      if (s.documentation.returns.type) {
+        retParts.push(md.text(" "));
+        retParts.push(md.inlineCode(s.documentation.returns.type));
+      }
+      retParts.push(md.text(" \u2014 "), ...parseInline(s.documentation.returns.description));
+      nodes.push(md.paragraph(...retParts));
     }
     const throws = s.documentation?.throws ?? [];
     if (throws.length > 0) {
-      lines.push("**Throws**");
-      lines.push("");
+      nodes.push(md.paragraph(md.strong(md.text("Throws"))));
+      const throwItems = [];
       for (const t of throws) {
-        const typeStr = t.type ? `\`${t.type}\` \u2014 ` : "";
-        lines.push(`- ${typeStr}${t.description}`);
+        const throwParts = [];
+        if (t.type) {
+          throwParts.push(md.inlineCode(t.type));
+          throwParts.push(md.text(" \u2014 "), ...parseInline(t.description));
+        } else {
+          throwParts.push(...parseInline(t.description));
+        }
+        throwItems.push(md.listItem(md.paragraph(...throwParts)));
       }
-      lines.push("");
+      nodes.push(md.list(throwItems));
     }
     const examples = s.documentation?.examples ?? [];
     if (examples.length > 0) {
       const ex = examples[0];
-      lines.push("**Example**");
-      lines.push("");
-      lines.push(`\`\`\`${ex.language || "typescript"}`);
-      lines.push(ex.code.trim());
-      lines.push("```");
-      lines.push("");
+      nodes.push(md.paragraph(md.strong(md.text("Example"))));
+      nodes.push(md.code(ex.language || "typescript", ex.code.trim()));
     }
     const methods = (s.children ?? []).filter((c) => c.kind === "method");
     if (methods.length > 0) {
-      lines.push("**Methods**");
-      lines.push("");
+      nodes.push(md.paragraph(md.strong(md.text("Methods"))));
       for (const method of methods) {
-        lines.push(`### ${method.name}()`);
-        lines.push("");
+        nodes.push(md.heading(3, md.text(`${method.name}()`)));
         if (method.documentation?.summary) {
-          lines.push(method.documentation.summary);
-          lines.push("");
+          nodes.push(md.paragraph(...parseInline(method.documentation.summary)));
         }
         if (method.signature) {
-          lines.push("```typescript");
-          lines.push(method.signature);
-          lines.push("```");
-          lines.push("");
+          nodes.push(md.code("typescript", method.signature));
         }
       }
     }
   }
   void packageName;
-  return lines.join("\n");
+  return serializeMarkdown(md.root(...nodes));
 }
 function renderExamplesPage(packageName, symbols, _options) {
   const exported = symbols.filter(
     (s) => s.exported && s.kind !== "method" && s.kind !== "property"
   );
-  const lines = [];
-  lines.push("All usage examples from the package, aggregated for quick reference.");
-  lines.push("");
+  const nodes = [];
+  nodes.push(textP("All usage examples from the package, aggregated for quick reference."));
   let hasExamples = false;
   for (const s of exported) {
     const examples = s.documentation?.examples ?? [];
     if (examples.length === 0) continue;
     hasExamples = true;
     const ext = s.kind === "function" ? "()" : "";
-    lines.push(`## \`${s.name}${ext}\``);
-    lines.push("");
+    nodes.push(md.heading(2, md.inlineCode(`${s.name}${ext}`)));
     if (s.documentation?.summary) {
-      lines.push(`_${s.documentation.summary}_`);
-      lines.push("");
-    }
-    lines.push(
-      `[View in API reference](${slugLink(`packages/${packageName}/api/functions`)}#${toAnchor2(s.name)})`
+      nodes.push(md.paragraph(md.emphasis(...parseInline(s.documentation.summary))));
+    }
+    nodes.push(
+      md.paragraph(
+        md.link(
+          `${slugLink(`packages/${packageName}/api/functions`)}#${toAnchor(s.name)}`,
+          md.text("View in API reference")
+        )
+      )
     );
-    lines.push("");
     for (const ex of examples) {
-      lines.push(`\`\`\`${ex.language || "typescript"}`);
-      lines.push(ex.code.trim());
-      lines.push("```");
-      lines.push("");
+      nodes.push(md.code(ex.language || "typescript", ex.code.trim()));
     }
   }
   if (!hasExamples) {
-    lines.push("_No examples documented yet._");
-    lines.push("");
+    nodes.push(md.paragraph(md.emphasis(md.text("No examples documented yet."))));
   }
-  return lines.join("\n");
+  return serializeMarkdown(md.root(...nodes));
 }
 function renderConfigurationPage(symbolsByPackage, options) {
   const configSymbol = [...symbolsByPackage.values()].flat().find((s) => s.exported && TYPE_KINDS.has(s.kind) && /config/i.test(s.name));
-  const lines = [];
-  lines.push(`Configuration reference for **${options.projectName}**.`);
-  lines.push("");
-  lines.push("## forge-ts.config.ts");
-  lines.push("");
-  lines.push("Create a `forge-ts.config.ts` file in your project root:");
-  lines.push("");
-  lines.push("```typescript");
-  lines.push('import { defineConfig } from "@forge-ts/core";');
-  lines.push("");
-  lines.push("export default defineConfig({");
-  lines.push('  rootDir: ".",');
-  lines.push('  outDir: "docs/generated",');
-  lines.push("});");
-  lines.push("```");
-  lines.push("");
+  const nodes = [];
+  nodes.push(
+    md.paragraph(
+      md.text("Configuration reference for "),
+      md.strong(md.text(options.projectName)),
+      md.text(".")
+    )
+  );
+  nodes.push(md.heading(2, md.text("forge-ts.config.ts")));
+  nodes.push(
+    md.paragraph(
+      md.text("Create a "),
+      md.inlineCode("forge-ts.config.ts"),
+      md.text(" file in your project root:")
+    )
+  );
+  nodes.push(
+    md.code(
+      "typescript",
+      [
+        'import { defineConfig } from "@forge-ts/core";',
+        "",
+        "export default defineConfig({",
+        '  rootDir: ".",',
+        '  outDir: "docs/generated",',
+        "});"
+      ].join("\n")
+    )
+  );
   if (configSymbol) {
-    lines.push(`## \`${configSymbol.name}\``);
-    lines.push("");
+    nodes.push(md.heading(2, md.inlineCode(configSymbol.name)));
     if (configSymbol.documentation?.summary) {
-      lines.push(configSymbol.documentation.summary);
-      lines.push("");
+      nodes.push(md.paragraph(...parseInline(configSymbol.documentation.summary)));
     }
     const children = (configSymbol.children ?? []).filter(
       (c) => c.kind === "property" || c.kind === "method"
     );
     if (children.length > 0) {
-      lines.push("| Property | Type | Required | Description |");
-      lines.push("|----------|------|----------|-------------|");
+      const headerRow = md.tableRow(
+        md.tableCell(md.text("Property")),
+        md.tableCell(md.text("Type")),
+        md.tableCell(md.text("Required")),
+        md.tableCell(md.text("Description"))
+      );
+      const dataRows = [];
       for (const child of children) {
-        const name = `\`${child.name}\``;
-        const type = child.signature ? `\`${escapePipe(child.signature)}\`` : "\u2014";
+        const typePhrasing = child.signature ? md.inlineCode(child.signature) : md.text("\u2014");
         const optional = child.signature?.includes("?") || child.signature?.includes("undefined") ? "No" : "Yes";
-        const description = escapePipe(child.documentation?.summary || child.name);
-        lines.push(`| ${name} | ${type} | ${optional} | ${description} |`);
+        const description = child.documentation?.summary || child.name;
+        dataRows.push(
+          md.tableRow(
+            md.tableCell(md.inlineCode(child.name)),
+            md.tableCell(typePhrasing),
+            md.tableCell(md.text(optional)),
+            md.tableCell(...parseInline(description))
+          )
+        );
       }
-      lines.push("");
+      nodes.push(md.table(null, headerRow, ...dataRows));
     }
   }
-  return lines.join("\n");
+  return serializeMarkdown(md.root(...nodes));
 }
 function renderChangelogPage(options) {
   const repoUrl = options.repositoryUrl ?? "";
-  const changelogLink = repoUrl ? `See [CHANGELOG.md](${repoUrl}/blob/main/CHANGELOG.md) for the full release history.` : "See your project's `CHANGELOG.md` for the full release history.";
-  return [
-    `Release history for **${options.projectName}**.`,
-    "",
-    "> This is a stub page. Link to or embed your `CHANGELOG.md` here.",
-    "",
-    changelogLink,
-    ""
-  ].join("\n");
+  const nodes = [];
+  nodes.push(
+    md.paragraph(
+      md.text("Release history for "),
+      md.strong(md.text(options.projectName)),
+      md.text(".")
+    )
+  );
+  nodes.push(
+    md.blockquote(textP("This is a stub page. Link to or embed your `CHANGELOG.md` here."))
+  );
+  if (repoUrl) {
+    nodes.push(
+      md.paragraph(
+        md.text("See "),
+        md.link(`${repoUrl}/blob/main/CHANGELOG.md`, md.text("CHANGELOG.md")),
+        md.text(" for the full release history.")
+      )
+    );
+  } else {
+    nodes.push(
+      md.paragraph(
+        md.text("See your project's "),
+        md.inlineCode("CHANGELOG.md"),
+        md.text(" for the full release history.")
+      )
+    );
+  }
+  return serializeMarkdown(md.root(...nodes));
 }
 function renderFaqPage(options) {
-  return [
-    `Frequently asked questions about **${options.projectName}**.`,
-    "",
-    "> This is a stub page. Common questions will be added here as they arise.",
-    "",
-    "## How do I configure forge-ts?",
-    "",
-    "Create a `forge-ts.config.ts` file in your project root. See [Configuration](/configuration).",
-    "",
-    "## What TypeScript version is required?",
-    "",
-    "forge-ts requires TypeScript 5.0 or later.",
-    "",
-    "## How do I run @example blocks as tests?",
-    "",
-    "```bash",
-    "npx forge-ts test",
-    "```",
-    ""
-  ].join("\n");
+  const nodes = [];
+  nodes.push(
+    md.paragraph(
+      md.text("Frequently asked questions about "),
+      md.strong(md.text(options.projectName)),
+      md.text(".")
+    )
+  );
+  nodes.push(
+    md.blockquote(textP("This is a stub page. Common questions will be added here as they arise."))
+  );
+  nodes.push(md.heading(2, md.text("How do I configure forge-ts?")));
+  nodes.push(
+    md.paragraph(
+      md.text("Create a "),
+      md.inlineCode("forge-ts.config.ts"),
+      md.text(" file in your project root. See "),
+      md.link("/configuration", md.text("Configuration")),
+      md.text(".")
+    )
+  );
+  nodes.push(md.heading(2, md.text("What TypeScript version is required?")));
+  nodes.push(textP("forge-ts requires TypeScript 5.0 or later."));
+  nodes.push(md.heading(2, md.text("How do I run @example blocks as tests?")));
+  nodes.push(md.code("bash", "npx forge-ts test"));
+  return serializeMarkdown(md.root(...nodes));
 }
 function renderContributingPage(options) {
   const repoUrl = options.repositoryUrl ?? "";
-  const contribLink = repoUrl ? `See [CONTRIBUTING.md](${repoUrl}/blob/main/CONTRIBUTING.md) for contribution guidelines.` : "See your project's `CONTRIBUTING.md` for contribution guidelines.";
-  return [
-    `Contributing to **${options.projectName}**.`,
-    "",
-    "> This is a stub page. Link to or embed your `CONTRIBUTING.md` here.",
-    "",
-    contribLink,
-    ""
-  ].join("\n");
+  const nodes = [];
+  nodes.push(
+    md.paragraph(
+      md.text("Contributing to "),
+      md.strong(md.text(options.projectName)),
+      md.text(".")
+    )
+  );
+  nodes.push(
+    md.blockquote(textP("This is a stub page. Link to or embed your `CONTRIBUTING.md` here."))
+  );
+  if (repoUrl) {
+    nodes.push(
+      md.paragraph(
+        md.text("See "),
+        md.link(`${repoUrl}/blob/main/CONTRIBUTING.md`, md.text("CONTRIBUTING.md")),
+        md.text(" for contribution guidelines.")
+      )
+    );
+  } else {
+    nodes.push(
+      md.paragraph(
+        md.text("See your project's "),
+        md.inlineCode("CONTRIBUTING.md"),
+        md.text(" for contribution guidelines.")
+      )
+    );
+  }
+  return serializeMarkdown(md.root(...nodes));
 }
 function generateDocSite(symbolsByPackage, config, options) {
   const ext = options.format === "mdx" ? "mdx" : "md";
@@ -2679,39 +3071,6 @@ import { existsSync as existsSync2 } from "fs";
 import { mkdir, readFile as readFile2, writeFile as writeFile2 } from "fs/promises";
 import { dirname, join } from "path";
 import { createWalker } from "@forge-ts/core";
-function updateAutoSections(existing, generated) {
-  const htmlPattern = /<!-- FORGE:AUTO-START (\S+) -->([\s\S]*?)<!-- FORGE:AUTO-END \1 -->/g;
-  const mdxGenPattern = /\{\/\*\s*FORGE:AUTO-START (\S+)\s*\*\/\}([\s\S]*?)\{\/\*\s*FORGE:AUTO-END \1\s*\*\/\}/g;
-  const newSections = /* @__PURE__ */ new Map();
-  let match;
-  while ((match = htmlPattern.exec(generated)) !== null) {
-    newSections.set(match[1], match[0]);
-  }
-  while ((match = mdxGenPattern.exec(generated)) !== null) {
-    if (!newSections.has(match[1])) {
-      newSections.set(match[1], match[0]);
-    }
-  }
-  if (newSections.size === 0) return null;
-  let updated = existing;
-  let changed = false;
-  for (const [id, replacement] of newSections) {
-    const htmlSectionPattern = new RegExp(
-      `<!-- FORGE:AUTO-START ${id} -->[\\s\\S]*?<!-- FORGE:AUTO-END ${id} -->`
-    );
-    const mdxSectionPattern = new RegExp(
-      `\\{/\\*\\s*FORGE:AUTO-START ${id}\\s*\\*/\\}[\\s\\S]*?\\{/\\*\\s*FORGE:AUTO-END ${id}\\s*\\*/\\}`
-    );
-    if (htmlSectionPattern.test(updated)) {
-      updated = updated.replace(htmlSectionPattern, replacement);
-      changed = true;
-    } else if (mdxSectionPattern.test(updated)) {
-      updated = updated.replace(mdxSectionPattern, replacement);
-      changed = true;
-    }
-  }
-  return changed ? updated : null;
-}
 async function generate(config, options) {
   const start = Date.now();
   const forceStubs = options?.forceStubs ?? false;
@@ -2824,7 +3183,18 @@ export {
   getAdapter,
   getAvailableTargets,
   groupSymbolsByPackage,
+  md,
+  parseBlocks,
+  parseFrontmatter,
+  parseInline,
   registerAdapter,
-  syncReadme
+  sanitizeForMdx,
+  serializeMarkdown,
+  slugLink,
+  stringifyWithFrontmatter,
+  stripFrontmatter,
+  syncReadme,
+  toAnchor,
+  truncate
 };
 //# sourceMappingURL=index.js.map