reallysimpledocs 1.0.0-beta.2 → 1.0.0-beta.4

package/src/runtime/lib/docs.js

@@ -2,8 +2,9 @@ import fs from "node:fs";
 import path from "node:path";
 import { marked } from "marked";
 import GithubSlugger from "github-slugger";
-import { codeToHtml } from "shiki";
 import * as lucideIcons from "lucide-static";
+import { highlightCode as renderHighlightedCode } from "./highlight.js";
+import { mdxToMarkdown } from "./markdown-export.js";
 import { markdownPath, routePath } from "./paths.js";
 
 export function getManifest(config) {
@@ -82,8 +83,14 @@ export function getDocMarkdown(config, page) {
   return fs.readFileSync(filePath, "utf8");
 }
 
-export function getMarkdownExport(config, page) {
-  return `${getDocMarkdown(config, page).trim()}\n`;
+export async function getMarkdownExport(config, page) {
+  const source = getDocMarkdown(config, page);
+  if (page.extension === ".mdx") return await mdxToMarkdown(source, config);
+  return `${source.trim()}\n`;
+}
+
+export async function getMarkdownBodyExport(config, page) {
+  return parseDocMarkdown(await getMarkdownExport(config, page), page.title).body.trim();
 }
 
 export async function renderDoc(config, page) {
@@ -117,7 +124,7 @@ export async function renderDoc(config, page) {
   };
 
   const tokens = marked.lexer(content);
-  await highlightCode(tokens);
+  await highlightMarkdownCode(tokens);
   const html = marked.parser(tokens, { renderer });
   return { page, html, headings };
 }
@@ -152,6 +159,46 @@ export function getNavigation(config, page) {
   };
 }
 
+export function getBreadcrumbs(config, page) {
+  const pages = getPages(config);
+  const bySlug = new Map(pages.map((entry) => [entry.slug, entry]));
+  const trail = [];
+
+  const walk = (items = [], ancestors = []) => {
+    for (const item of items) {
+      if (item?.type === "group") {
+        const result = walk(item.items || [], ancestors);
+        if (result) return result;
+        continue;
+      }
+
+      if (item?.type === "submenu") {
+        const result = walk(item.items || [], item.label ? [...ancestors, { label: item.label }] : ancestors);
+        if (result) return result;
+        continue;
+      }
+
+      const slug = typeof item === "string" ? item : getPageItemSlug(item);
+      if (slug !== page.slug) continue;
+      const matchedPage = bySlug.get(slug);
+      if (!matchedPage) return ancestors;
+      return [
+        ...ancestors,
+        {
+          label: item.label || matchedPage.title,
+          url: matchedPage.path,
+        },
+      ];
+    }
+    return null;
+  };
+
+  const manifest = getManifest(config);
+  const found = walk(manifest.menu || []);
+  if (found) trail.push(...found);
+  return trail;
+}
+
 export function resolveIcon(icon) {
   if (!icon || typeof icon !== "string") return "";
   const trimmed = icon.trim();
@@ -164,7 +211,9 @@ export function resolveIcon(icon) {
         .join("")
     : trimmed.charAt(0).toUpperCase() + trimmed.slice(1);
   const iconClass = trimmed.replace(/([a-z0-9])([A-Z])/g, "$1-$2").toLowerCase();
-  return lucideIcons[pascalName]?.replace('class="lucide', `class="lucide lucide-${iconClass}`) || "";
+  const svg = lucideIcons[pascalName] || "";
+  if (!svg || svg.includes(`lucide-${iconClass}`)) return svg;
+  return svg.replace('class="lucide', `class="lucide lucide-${iconClass}`);
 }
 
 export function buildMenus(config, currentSlug) {
@@ -185,10 +234,30 @@ export function buildMenus(config, currentSlug) {
     };
   };
 
+  const processExternalLink = (item) => {
+    if (!item?.url || !item?.label) return null;
+    const external = isExternalUrl(item.url);
+    const attrs = {
+      ...item.attrs,
+      target: external ? item.attrs?.target || "_blank" : item.attrs?.target,
+      rel: external ? item.attrs?.rel || "noopener" : item.attrs?.rel,
+    };
+    return {
+      type: "item",
+      icon: resolveIcon(item.icon),
+      url: item.url,
+      label: item.label,
+      external,
+      attrs,
+      keywords: item.label,
+    };
+  };
+
   const processItem = (item) => {
     if (typeof item === "string") return processSlug(item);
     const slug = getPageItemSlug(item);
     if (slug) return processSlug(slug, item);
+    if (item?.url) return processExternalLink(item);
     if (item?.type === "submenu") {
       const items = (item.items || []).map(processItem).filter(Boolean);
       return {
@@ -218,6 +287,8 @@ export function buildMenus(config, currentSlug) {
       icon: item.icon,
       url: item.url,
       label: item.label,
+      external: item.external,
+      attrs: item.attrs,
       keywords: item.keywords,
     })),
   }));
@@ -225,23 +296,28 @@ export function buildMenus(config, currentSlug) {
   return { sidebar, command };
 }
 
-export function getLlmDocs(config) {
-  return getPages(config).map((page) => ({
-    ...page,
-    content: parseDocMarkdown(getDocMarkdown(config, page), page.title).body.trim(),
-  }));
+export async function getLlmDocs(config) {
+  const docs = [];
+  for (const page of getPages(config)) {
+    docs.push({
+      ...page,
+      content: await getMarkdownBodyExport(config, page),
+    });
+  }
+  return docs;
 }
 
-export function getSearchDocs(config) {
-  return getPages(config).map((page) => {
-    const parsed = parseDocMarkdown(getDocMarkdown(config, page), page.title);
-    return {
+export async function getSearchDocs(config) {
+  const docs = [];
+  for (const page of getPages(config)) {
+    docs.push({
       slug: page.slug,
       title: page.title,
       path: page.path,
-      body: markdownPlainText(parsed.body),
-    };
-  });
+      body: markdownPlainText(await getMarkdownBodyExport(config, page)),
+    });
+  }
+  return docs;
 }
 
 function flattenSidebarItems(items = []) {
@@ -253,6 +329,10 @@ export function getPageItemSlug(item) {
   return item.slug || item.page || "";
 }
 
+function isExternalUrl(url) {
+  return /^[a-z][a-z0-9+.-]*:/i.test(String(url || ""));
+}
+
 function parseDocMarkdown(source, fallbackTitle) {
   const content = normalizeDocSource(source);
   const tokens = marked.lexer(content);
@@ -282,11 +362,11 @@ function normalizeDocSource(source) {
   const firstHeading = withoutFrontmatter.search(/^#\s+/m);
   if (firstHeading > 0) return withoutFrontmatter.slice(firstHeading).trimStart();
   return withoutFrontmatter
-    .replace(/^(\s*(?:import|export)\s+[^\n]*\n)+/m, "")
+    .replace(/^(?:[ \t]*(?:import|export)\s+[^\n]*\n)+/, "")
     .trimStart();
 }
 
-async function highlightCode(tokens) {
+async function highlightMarkdownCode(tokens) {
   for (const token of tokens) {
     if (token.type === "code") {
       const html = await highlightToken(token);
@@ -300,33 +380,24 @@ async function highlightCode(tokens) {
     }
 
     for (const childTokens of nestedTokenLists(token)) {
-      await highlightCode(childTokens);
+      await highlightMarkdownCode(childTokens);
     }
   }
 }
 
 async function highlightToken(token) {
+  const lang = normalizeLanguage(token.lang);
   try {
-    return await codeToHtml(token.text, {
-      lang: normalizeLanguage(token.lang),
-      themes: {
-        light: "github-light",
-        dark: "github-dark",
-      },
-      defaultColor: false,
-    });
+    return wrapCodeBlock(await renderHighlightedCode(token.text, lang));
   } catch {
-    return codeToHtml(token.text, {
-      lang: "text",
-      themes: {
-        light: "github-light",
-        dark: "github-dark",
-      },
-      defaultColor: false,
-    });
+    return wrapCodeBlock(await renderHighlightedCode(token.text, "text"));
   }
 }
 
+function wrapCodeBlock(html) {
+  return `<div class="relative my-6 w-full max-w-full overflow-hidden rounded-lg" data-code-block>${html}</div>`;
+}
+
 function normalizeLanguage(lang) {
   const value = lang?.trim().split(/\s+/)[0].toLowerCase() || "text";
   if (value === "njk") return "html";

package/src/runtime/lib/highlight.js

@@ -0,0 +1,27 @@
+import { codeToHtml } from "shiki";
+
+export async function highlightCode(code, lang = "text") {
+  const value = String(code || "");
+  const language = String(lang || "text").toLowerCase() === "mdx" ? "tsx" : String(lang || "text");
+  const html = await codeToHtml(value, {
+    lang: language,
+    themes: {
+      light: "github-light",
+      dark: "github-dark",
+    },
+    defaultColor: false,
+  });
+  return addCodeLayoutClasses(html);
+}
+
+function addCodeLayoutClasses(html) {
+  return String(html)
+    .replace(
+      /<pre class="/,
+      '<pre class="!my-0 max-w-full overflow-x-auto !rounded-none !border-0 ',
+    )
+    .replace(
+      /<code>/,
+      '<code class="block min-w-full w-max px-4 py-3 text-[13px]">',
+    );
+}

package/src/runtime/lib/macros.js

@@ -1,6 +1,9 @@
+import ArrowUpRight from "lucide-static/icons/arrow-up-right.svg?raw";
 import Search from "lucide-static/icons/search.svg?raw";
 import { attrs, escapeHtml } from "./html.js";
 
+const externalLinkIcon = ArrowUpRight.replace('class="lucide', 'class="lucide ml-auto size-3.5 shrink-0');
+
 export function renderSidebar({
   id = "sidebar",
   label = "Sidebar navigation",
@@ -58,6 +61,7 @@ export function renderSidebarContent(items = [], parentIdPrefix = "content") {
   <a${attrs({ href: item.url, "aria-current": item.current ? "page" : undefined, ...without(item.attrs, ["href", "aria-current"]) })}>
     ${item.icon || ""}
     <span>${escapeHtml(item.label)}</span>
+    ${item.external ? externalLinkIcon : ""}
   </a>
 </li>`;
     })
@@ -67,7 +71,7 @@ export function renderSidebarContent(items = [], parentIdPrefix = "content") {
 export function renderCommandDialog({
   id = "command-search",
   items = [],
-  placeholder = "Search the docs...",
+  placeholder = "Search...",
   emptyText = "No results found.",
   open = false,
   commandAttrs = {},

package/src/runtime/lib/markdown-export.js

@@ -0,0 +1,200 @@
+import { gfmToMarkdown } from "mdast-util-gfm";
+import { toMarkdown } from "mdast-util-to-markdown";
+import remarkGfm from "remark-gfm";
+import remarkMdx from "remark-mdx";
+import remarkParse from "remark-parse";
+import { unified } from "unified";
+import { serializeComponent } from "./markdown-exporters/index.js";
+import { getMdxChildrenSource, trimCode } from "./mdx-source.js";
+
+const processor = unified().use(remarkParse).use(remarkGfm).use(remarkMdx);
+
+const customSerializersCache = new Map();
+
+export async function mdxToMarkdown(source, options = {}) {
+  const tree = processor.parse(source);
+  const state = {
+    constants: collectExportedStrings(tree),
+    customSerializers: await loadCustomSerializers(options.markdownSerializers),
+    source: String(source || ""),
+  };
+  const children = await transformBlocks(tree.children || [], state);
+  return `${stringify({ type: "root", children }).trim()}\n`;
+}
+
+async function loadCustomSerializers(entries = {}) {
+  const cacheKey = JSON.stringify(entries || {});
+  if (customSerializersCache.has(cacheKey)) return customSerializersCache.get(cacheKey);
+
+  const serializers = {};
+  for (const [name, moduleId] of Object.entries(entries || {})) {
+    if (!moduleId) continue;
+    const module = await import(/* @vite-ignore */ moduleId);
+    const serializer = module.default || module.serialize;
+    if (typeof serializer !== "function") {
+      throw new Error(`Markdown serializer for "${name}" must export a function as default or serialize.`);
+    }
+    serializers[name] = serializer;
+  }
+
+  customSerializersCache.set(cacheKey, serializers);
+  return serializers;
+}
+
+async function transformBlocks(nodes, state) {
+  const blocks = [];
+  for (const node of nodes) {
+    blocks.push(...(await transformBlock(node, state)));
+  }
+  return blocks.filter(Boolean);
+}
+
+async function transformBlock(node, state) {
+  if (!node) return [];
+
+  if (node.type === "mdxjsEsm") return [];
+
+  if (isMdxElement(node)) {
+    return await transformComponent(node, state);
+  }
+
+  if (node.type === "paragraph") {
+    const children = significantChildren(node.children || []);
+    if (children.length === 1 && isMdxElement(children[0])) {
+      return await transformComponent(children[0], state);
+    }
+  }
+
+  const clone = { ...node };
+  if (Array.isArray(clone.children)) {
+    if (isBlockContainer(clone.type)) {
+      clone.children = await transformBlocks(clone.children, state);
+    } else {
+      clone.children = await transformInline(clone.children, state);
+    }
+  }
+  return [clone];
+}
+
+async function transformComponent(node, state) {
+  return (
+    (await serializeComponent(
+      node,
+      {
+        transformBlocks: (nodes) => transformBlocks(nodes, state),
+        getAttr: (entry, name) => getAttr(entry, name, state.constants),
+        getCodeValue: (entry) => getCodeValue(entry, state.constants),
+        getChildrenSource: (entry) => getMdxChildrenSource(entry, state.source),
+        isNamedElement,
+        significantChildren,
+      },
+      state.customSerializers,
+    )) || (await transformBlocks(node.children || [], state))
+  );
+}
+
+async function transformInline(nodes, state) {
+  const inline = [];
+  for (const node of nodes) {
+    if (isMdxElement(node)) {
+      const text = stringify({ type: "root", children: await transformComponent(node, state) }).trim();
+      if (text) inline.push({ type: "text", value: text });
+      continue;
+    }
+    if (node.type === "mdxTextExpression" || node.type === "mdxFlowExpression") {
+      const value = expressionValue(node, state.constants);
+      if (value) inline.push({ type: "text", value });
+      continue;
+    }
+    const clone = { ...node };
+    if (Array.isArray(clone.children)) clone.children = await transformInline(clone.children, state);
+    inline.push(clone);
+  }
+  return inline;
+}
+
+function getCodeValue(node, constants) {
+  const parts = (node.children || []).map((child) => {
+    if (child.type === "text") return child.value || "";
+    if (child.type === "mdxFlowExpression" || child.type === "mdxTextExpression") {
+      return expressionValue(child, constants);
+    }
+    return "";
+  });
+  return trimCode(parts.join("") || String(getAttr(node, "code", constants) || ""));
+}
+
+function getAttr(node, name, constants) {
+  const attr = (node.attributes || []).find((entry) => entry.type === "mdxJsxAttribute" && entry.name === name);
+  if (!attr) return "";
+  if (attr.value == null) return "true";
+  if (typeof attr.value === "string") return attr.value;
+  return expressionValue(attr.value, constants);
+}
+
+function collectExportedStrings(tree) {
+  const constants = new Map();
+  for (const node of tree.children || []) {
+    if (node.type !== "mdxjsEsm") continue;
+    for (const statement of node.data?.estree?.body || []) {
+      if (statement.type !== "ExportNamedDeclaration") continue;
+      if (statement.declaration?.type !== "VariableDeclaration") continue;
+      for (const declaration of statement.declaration.declarations || []) {
+        if (declaration.id?.type !== "Identifier") continue;
+        const value = staticValue(declaration.init, constants);
+        if (value) constants.set(declaration.id.name, value);
+      }
+    }
+  }
+  return constants;
+}
+
+function expressionValue(node, constants) {
+  const expression = node.data?.estree?.body?.[0]?.expression || node.data?.estree?.body?.[0];
+  return staticValue(expression, constants) || "";
+}
+
+function staticValue(node, constants) {
+  if (!node) return "";
+  if (node.type === "Literal") return node.value ?? "";
+  if (node.type === "TemplateLiteral" && node.expressions.length === 0) {
+    return node.quasis.map((quasi) => quasi.value.cooked ?? quasi.value.raw ?? "").join("");
+  }
+  if (node.type === "Identifier") return constants.get(node.name) || "";
+  if (node.type === "ObjectExpression") {
+    return Object.fromEntries(
+      node.properties
+        .filter((property) => property.type === "Property")
+        .map((property) => [property.key.name || property.key.value, staticValue(property.value, constants)]),
+    );
+  }
+  if (node.type === "ArrayExpression") {
+    return node.elements.map((element) => staticValue(element, constants));
+  }
+  return "";
+}
+
+function stringify(tree) {
+  return toMarkdown(tree, {
+    bullet: "-",
+    fences: true,
+    rule: "-",
+    extensions: [gfmToMarkdown()],
+  });
+}
+
+function isMdxElement(node) {
+  return node?.type === "mdxJsxFlowElement" || node?.type === "mdxJsxTextElement";
+}
+
+function isNamedElement(node, name) {
+  return isMdxElement(node) && node.name === name;
+}
+
+function significantChildren(children) {
+  return children.filter((child) => child.type !== "text" || child.value.trim());
+}
+
+function isBlockContainer(type) {
+  return type === "root" || type === "blockquote" || type === "list" || type === "listItem";
+}

package/src/runtime/lib/markdown-exporters/index.js

@@ -0,0 +1,144 @@
+const serializers = {
+  Callout: renderCallout,
+  Code: renderCode,
+  CodeGroup: renderCodeGroup,
+  Preview: renderPreview,
+  Steps: renderSteps,
+  Tabs: renderChildren,
+  Card: renderCard,
+  CardGrid: renderCardGrid,
+};
+
+export async function serializeComponent(node, context, customSerializers = {}) {
+  if (customSerializers[node.name]) return await customSerializers[node.name](node, context);
+  return serializers[node.name]?.(node, context) || null;
+}
+
+async function renderChildren(node, context) {
+  return await context.transformBlocks(node.children || []);
+}
+
+async function renderCallout(node, context) {
+  const title = context.getAttr(node, "title");
+  const action = context.getAttr(node, "action");
+  const children = await context.transformBlocks(node.children || []);
+  const quoteChildren = [];
+  if (title) quoteChildren.push(strongParagraph(title));
+  quoteChildren.push(...children);
+  if (action?.label) {
+    quoteChildren.push({
+      type: "paragraph",
+      children: action.href
+        ? [{ type: "link", url: action.href, children: [{ type: "text", value: action.label }] }]
+        : [{ type: "strong", children: [{ type: "text", value: action.label }] }],
+    });
+  }
+  return [{ type: "blockquote", children: quoteChildren }];
+}
+
+function renderCode(node, context) {
+  const title = context.getAttr(node, "title") || context.getAttr(node, "slot");
+  const lang = context.getAttr(node, "lang") || "text";
+  const value = context.getCodeValue(node);
+  const blocks = [];
+  if (title) blocks.push(strongParagraph(title));
+  blocks.push({ type: "code", lang, value });
+  return blocks;
+}
+
+function renderCodeGroup(node, context) {
+  const codeNodes = collectCodeChildren(node, context);
+  if (!codeNodes.length) return renderChildren(node, context);
+  return codeNodes.flatMap((child, index) => {
+    const blocks = renderCode(child, context);
+    return index === 0 ? blocks : [{ type: "thematicBreak" }, ...blocks];
+  });
+}
+
+async function renderPreview(node, context) {
+  const value = context.getAttr(node, "code") || context.getChildrenSource(node);
+  if (value) {
+    return [{ type: "code", lang: context.getAttr(node, "lang") || "mdx", value }];
+  }
+  return await renderChildren(node, context);
+}
+
+async function renderSteps(node, context) {
+  const steps = (node.children || []).filter((child) => context.isNamedElement(child, "Step"));
+  if (!steps.length) return await renderChildren(node, context);
+  const children = [];
+  for (const step of steps) {
+    children.push({
+      type: "listItem",
+      spread: true,
+      children: await stepToBlocks(step, context),
+    });
+  }
+  return [
+    {
+      type: "list",
+      ordered: true,
+      spread: true,
+      children,
+    },
+  ];
+}
+
+function renderCard(node, context) {
+  return [cardList([node], context)];
+}
+
+function renderCardGrid(node, context) {
+  return [cardList((node.children || []).filter((child) => context.isNamedElement(child, "Card")), context)];
+}
+
+async function stepToBlocks(node, context) {
+  const title = context.getAttr(node, "title");
+  const children = await context.transformBlocks(node.children || []);
+  if (!title) return children;
+  return [strongParagraph(title), ...children];
+}
+
+function cardList(cards, context) {
+  return {
+    type: "list",
+    ordered: false,
+    spread: true,
+    children: cards.map((card) => ({
+      type: "listItem",
+      spread: false,
+      children: [cardParagraph(card, context)],
+    })),
+  };
+}
+
+function cardParagraph(node, context) {
+  const title = context.getAttr(node, "title") || "Card";
+  const description = context.getAttr(node, "description");
+  const href = context.getAttr(node, "href");
+  const titleNode =
+    href && href !== "#"
+      ? { type: "link", url: href, children: [{ type: "text", value: title }] }
+      : { type: "strong", children: [{ type: "text", value: title }] };
+  return {
+    type: "paragraph",
+    children: description ? [titleNode, { type: "text", value: `: ${description}` }] : [titleNode],
+  };
+}
+
+function collectCodeChildren(node, context) {
+  return (node.children || []).flatMap((child) => {
+    if (context.isNamedElement(child, "Code")) return [child];
+    if (child.type === "paragraph") {
+      return context.significantChildren(child.children || []).filter((entry) => context.isNamedElement(entry, "Code"));
+    }
+    return [];
+  });
+}
+
+function strongParagraph(value) {
+  return {
+    type: "paragraph",
+    children: [{ type: "strong", children: [{ type: "text", value }] }],
+  };
+}

package/src/runtime/lib/mdx-source.js

@@ -0,0 +1,19 @@
+export function getMdxChildrenSource(node, source) {
+  const children = node?.children || [];
+  const first = children[0];
+  const last = children.at(-1);
+  const start = first?.position?.start?.offset;
+  const end = last?.position?.end?.offset;
+  if (!Number.isFinite(start) || !Number.isFinite(end) || end <= start) return "";
+  return trimCode(String(source || "").slice(start, end));
+}
+
+export function trimCode(value) {
+  const lines = String(value || "").replace(/\r\n/g, "\n").split("\n");
+  while (lines.length && !lines[0].trim()) lines.shift();
+  while (lines.length && !lines.at(-1).trim()) lines.pop();
+  const indent = lines
+    .filter((line) => line.trim())
+    .reduce((min, line) => Math.min(min, line.match(/^\s*/)[0].length), Infinity);
+  return lines.map((line) => line.slice(Number.isFinite(indent) ? indent : 0)).join("\n");
+}

package/src/runtime/lib/preview-source-plugin.js

@@ -0,0 +1,33 @@
+import { getMdxChildrenSource } from "./mdx-source.js";
+
+export function previewSourceRemarkPlugin() {
+  return (tree, file) => {
+    const source = String(file.value || "");
+    walk(tree, (node) => {
+      if (!isPreview(node) || hasAttribute(node, "code")) return;
+      const code = getMdxChildrenSource(node, source);
+      node.attributes = [
+        ...(node.attributes || []),
+        {
+          type: "mdxJsxAttribute",
+          name: "code",
+          value: code,
+        },
+      ];
+    });
+  };
+}
+
+function walk(node, callback) {
+  if (!node || typeof node !== "object") return;
+  callback(node);
+  for (const child of node.children || []) walk(child, callback);
+}
+
+function isPreview(node) {
+  return node?.type === "mdxJsxFlowElement" && node.name === "Preview";
+}
+
+function hasAttribute(node, name) {
+  return (node.attributes || []).some((attr) => attr.type === "mdxJsxAttribute" && attr.name === name);
+}