reallysimpledocs 1.0.0-beta.3 → 1.0.0-beta.4

package/src/runtime/components/Sidebar.astro

@@ -1,6 +1,7 @@
 ---
 import config from "virtual:reallysimpledocs/config";
 import SidebarHeader from "virtual:reallysimpledocs/components/SidebarHeader";
+import SidebarFooter from "virtual:reallysimpledocs/components/SidebarFooter";
 import { renderSidebarContent } from "../lib/macros.js";
 import { getSite } from "../lib/site.js";
 
@@ -16,5 +17,8 @@ const site = getSite(config);
     <section class="scrollbar">
       <Fragment set:html={renderSidebarContent(menu, "sidebar-content")} />
     </section>
+    <footer>
+      <SidebarFooter site={site} />
+    </footer>
   </nav>
 </aside>

package/src/runtime/components/mdx/Callout.astro

@@ -2,10 +2,22 @@
 import * as lucideIcons from "lucide-static";
 import { addSvgClass } from "../../lib/html.js";
 
-const { type, title = "Note", icon: iconName, class: className = "" } = Astro.props;
+const { type, title = "Note", icon: iconName, action, class: className = "" } = Astro.props;
 const normalizedType = String(type || "").toLowerCase();
-const calloutType = normalizedType === "warning" || normalizedType === "danger" ? normalizedType : "";
-const danger = calloutType === "danger";
+const calloutType = normalizedType === "warning" || normalizedType === "destructive" ? normalizedType : "";
+const destructive = calloutType === "destructive";
+const actionLabel = action?.label;
+const actionClass = action?.class || "btn-sm-secondary";
+const actionAttrs = action
+  ? {
+      ...action.attrs,
+      href: action.href,
+      target: action.target,
+      rel: action.rel,
+      onclick: action.onclick,
+      class: actionClass,
+    }
+  : {};
 
 function resolveNamedIcon(name) {
   if (!name || typeof name !== "string") return "";
@@ -27,15 +39,26 @@ const heading = title;
 const variantClass =
   calloutType === "warning"
     ? "[&>svg]:text-amber-700 [&>h3]:text-amber-700 [&>section]:text-amber-700 dark:[&>svg]:text-amber-300 dark:[&>h3]:text-amber-300 dark:[&>section]:text-amber-300"
-    : danger
+    : destructive
       ? "[&>svg]:text-destructive [&>h3]:text-destructive [&>section]:text-destructive"
       : "";
 ---
 
-<div class:list={[danger ? "alert-destructive" : "alert", "my-6", variantClass, className]}>
+<div class:list={[destructive ? "alert-destructive" : "alert", "my-6", variantClass, className]}>
   {icon && <Fragment set:html={icon} />}
   <h3>{heading}</h3>
   <section>
     <slot />
   </section>
+  {
+    actionLabel && (
+      <footer>
+        {action?.href ? (
+          <a {...actionAttrs}>{actionLabel}</a>
+        ) : (
+          <button type="button" {...actionAttrs}>{actionLabel}</button>
+        )}
+      </footer>
+    )
+  }
 </div>

package/src/runtime/components/mdx/Preview.astro

@@ -7,7 +7,7 @@ const html = await highlightCode(code, lang);
 ---
 
 <section
-  class="relative my-6 max-w-full overflow-hidden rounded-lg border [&>[role=tabpanel]]:border-t-0 [&>[data-code-panel]_[data-code-block]]:my-0 [&>[data-code-panel]_[data-code-block]]:min-w-0 [&>[data-code-panel]_[data-code-block]]:rounded-none [&>[data-preview-panel]>div]:flex [&>[data-preview-panel]>div]:min-h-64 [&>[data-preview-panel]>div]:w-full [&>[data-preview-panel]>div]:items-center [&>[data-preview-panel]>div]:justify-center [&>[data-preview-panel]>div]:p-6"
+  class="relative my-6 max-w-full overflow-visible rounded-lg border [&>[role=tabpanel]]:border-t-0 [&>[data-code-panel]_[data-code-block]]:my-0 [&>[data-code-panel]_[data-code-block]]:min-w-0 [&>[data-code-panel]_[data-code-block]]:rounded-none"
   data-preview
 >
   <header class="flex h-10 items-center gap-2 border-b border-border/50 bg-muted/50 px-3 text-sm font-medium">
@@ -43,6 +43,7 @@ const html = await highlightCode(code, lang);
     aria-labelledby={`${id}-preview-tab`}
     tabindex="-1"
     aria-selected="true"
+    class="flex min-h-64 w-full items-center justify-center p-6"
   >
     <div class={className}>
       <slot />

package/src/runtime/lib/docs.js

@@ -4,6 +4,7 @@ import { marked } from "marked";
 import GithubSlugger from "github-slugger";
 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) {
@@ -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();
@@ -187,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 {
@@ -220,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,
     })),
   }));
@@ -227,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 = []) {
@@ -255,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);

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

package/src/runtime/lib/site.js

@@ -4,7 +4,6 @@ export const defaultSite = {
   title: "ReallySimpleDocs",
   description: "A really simple documentation site.",
   url: "",
-  links: [],
 };
 
 export function getSite(config) {