reallysimpledocs 0.1.3

package/src/runtime/lib/docs.js

@@ -0,0 +1,334 @@
+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 { markdownPath, routePath } from "./paths.js";
+
+export function getManifest(config) {
+  const manifestPath = path.join(config.docsDir, "docs.json");
+  return JSON.parse(fs.readFileSync(manifestPath, "utf8"));
+}
+
+export const fallbackLabelFromSlug = (slug) => {
+  if (slug === "index") return "Introduction";
+  const parts = String(slug).split("/");
+  const last = parts.at(-1);
+  const base = last === "index" && parts.length > 1 ? parts.at(-2) : last;
+  return base.replace(/-/g, " ").replace(/\b\w/g, (letter) => letter.toUpperCase());
+};
+
+export const slugToFile = (slug) => path.join(...String(slug).split("/")) + ".md";
+
+export function flattenMenuSlugs(menu) {
+  const out = [];
+  const walk = (items = []) => {
+    items.forEach((item) => {
+      if (typeof item === "string") {
+        out.push(item);
+      } else if (getPageItemSlug(item)) {
+        out.push(getPageItemSlug(item));
+      } else if (item?.type === "submenu") {
+        walk(item.items || []);
+      }
+    });
+  };
+
+  (menu || []).forEach((group) => {
+    if (group?.type === "group") walk(group.items || []);
+  });
+  return out;
+}
+
+export function getPages(config) {
+  const manifest = getManifest(config);
+  return flattenMenuSlugs(manifest.menu || []).map((slug) => {
+    const file = slugToFile(slug);
+    const filePath = path.join(config.docsDir, file);
+    const source = fs.readFileSync(filePath, "utf8");
+    const parsed = parseDocMarkdown(source, fallbackLabelFromSlug(slug));
+    return {
+      slug,
+      file,
+      path: routePath(config.routeBase, slug),
+      markdownPath: markdownPath(config.routeBase, slug),
+      title: parsed.title,
+    };
+  });
+}
+
+export function getPage(config, slug) {
+  const normalizedSlug = slug || "index";
+  return getPages(config).find((page) => page.slug === normalizedSlug);
+}
+
+export function getDocMarkdown(config, page) {
+  const filePath = path.resolve(config.docsDir, page.file);
+  const docsRoot = path.resolve(config.docsDir);
+  const relativePath = path.relative(docsRoot, filePath);
+  if (relativePath.startsWith("..") || path.isAbsolute(relativePath) || !fs.existsSync(filePath)) {
+    throw new Error(`Invalid docs page file for ${page.slug}: ${page.file}`);
+  }
+  return fs.readFileSync(filePath, "utf8");
+}
+
+export function getMarkdownExport(config, page) {
+  return `${getDocMarkdown(config, page).trim()}\n`;
+}
+
+export async function renderDoc(config, page) {
+  const parsed = parseDocMarkdown(getDocMarkdown(config, page), page.title);
+  const content = renderNunjucksCompat(parsed.body);
+  const headings = [];
+  const slugger = new GithubSlugger();
+  const renderer = new marked.Renderer();
+
+  renderer.heading = ({ tokens, depth }) => {
+    const text = renderer.parser.parseInline(tokens);
+    const headingText = plainText(tokens);
+    const id = slugger.slug(headingText);
+    if (depth > 1 && depth < 4) headings.push({ depth, id, text: headingText });
+    return `<h${depth} id="${id}" tabindex="-1"><a class="header-anchor" href="#${id}">${text}</a></h${depth}>`;
+  };
+
+  renderer.table = (token) => {
+    const header = renderer.tablerow({
+      text: token.header.map((cell) => renderer.tablecell(cell)).join(""),
+    });
+    const body = token.rows
+      .map((row) =>
+        renderer.tablerow({
+          text: row.map((cell) => renderer.tablecell(cell)).join(""),
+        }),
+      )
+      .join("");
+    const tbody = body ? `<tbody>${body}</tbody>` : "";
+    return `<div class="relative my-6 w-full overflow-auto"><table><thead>${header}</thead>${tbody}</table></div>`;
+  };
+
+  const tokens = marked.lexer(content);
+  await highlightCode(tokens);
+  const html = marked.parser(tokens, { renderer });
+  return { page, html, headings };
+}
+
+export function renderNunjucksCompat(content) {
+  return String(content).replace(
+    /\{%\s*lucide\s+["']([^"']+)["'](?:\s*,\s*[^%]+)?\s*%\}/g,
+    (_, icon) => resolveIcon(icon),
+  );
+}
+
+export function getNavigation(config, page) {
+  const pages = getPages(config);
+  const index = pages.findIndex((entry) => entry.slug === page.slug);
+  return {
+    prev: index > 0 ? pages[index - 1] : null,
+    next: index >= 0 && index < pages.length - 1 ? pages[index + 1] : null,
+  };
+}
+
+export function resolveIcon(icon) {
+  if (!icon || typeof icon !== "string") return "";
+  const trimmed = icon.trim();
+  if (!trimmed) return "";
+  if (trimmed.startsWith("<svg")) return trimmed;
+  const pascalName = trimmed.includes("-")
+    ? trimmed
+        .split("-")
+        .map((part) => part.charAt(0).toUpperCase() + part.slice(1))
+        .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}`) || "";
+}
+
+export function buildMenus(config, currentSlug) {
+  const pages = getPages(config);
+  const bySlug = new Map(pages.map((page) => [page.slug, page]));
+
+  const processSlug = (slug, item = {}) => {
+    const page = bySlug.get(slug);
+    if (!page) return null;
+    const icon = resolveIcon(item.icon);
+    return {
+      type: "item",
+      icon,
+      url: page.path,
+      label: page.title,
+      current: page.slug === currentSlug,
+      keywords: page.title,
+    };
+  };
+
+  const processItem = (item) => {
+    if (typeof item === "string") return processSlug(item);
+    const slug = getPageItemSlug(item);
+    if (slug) return processSlug(slug, item);
+    if (item?.type === "submenu") {
+      const items = (item.items || []).map(processItem).filter(Boolean);
+      return {
+        type: "submenu",
+        label: item.label,
+        icon: resolveIcon(item.icon),
+        open: item.open || items.some((child) => child.current),
+        items,
+      };
+    }
+    return null;
+  };
+
+  const sidebar = (getManifest(config).menu || [])
+    .filter((group) => group?.type === "group")
+    .map((group) => ({
+      type: "group",
+      label: group.label,
+      items: (group.items || []).map(processItem).filter(Boolean),
+    }));
+
+  const command = sidebar.map((group) => ({
+    type: "group",
+    label: group.label,
+    items: flattenSidebarItems(group.items).map((item) => ({
+      type: "item",
+      icon: item.icon,
+      url: item.url,
+      label: item.label,
+      keywords: item.keywords,
+    })),
+  }));
+
+  return { sidebar, command };
+}
+
+export function getLlmDocs(config) {
+  return getPages(config).map((page) => ({
+    ...page,
+    content: parseDocMarkdown(getDocMarkdown(config, page), page.title).body.trim(),
+  }));
+}
+
+export function getSearchDocs(config) {
+  return getPages(config).map((page) => {
+    const parsed = parseDocMarkdown(getDocMarkdown(config, page), page.title);
+    return {
+      slug: page.slug,
+      title: page.title,
+      path: page.path,
+      body: markdownPlainText(parsed.body),
+    };
+  });
+}
+
+function flattenSidebarItems(items = []) {
+  return items.flatMap((item) => (item.type === "submenu" ? flattenSidebarItems(item.items) : [item]));
+}
+
+export function getPageItemSlug(item) {
+  if (!item || typeof item !== "object" || item.type === "submenu") return "";
+  return item.slug || item.page || "";
+}
+
+function parseDocMarkdown(source, fallbackTitle) {
+  const content = String(source || "").trimStart();
+  const tokens = marked.lexer(content);
+  const first = tokens[0];
+
+  if (first?.type !== "heading" || first.depth !== 1) {
+    return {
+      title: fallbackTitle,
+      body: content,
+    };
+  }
+
+  return {
+    title: plainText(first.tokens || []).trim() || fallbackTitle,
+    body: content.slice(first.raw.length).trimStart(),
+  };
+}
+
+function markdownPlainText(markdown) {
+  return tokensText(marked.lexer(renderNunjucksCompat(markdown)));
+}
+
+async function highlightCode(tokens) {
+  for (const token of tokens) {
+    if (token.type === "code") {
+      const html = await highlightToken(token);
+      Object.assign(token, {
+        type: "html",
+        raw: html,
+        text: html,
+        block: true,
+      });
+      continue;
+    }
+
+    for (const childTokens of nestedTokenLists(token)) {
+      await highlightCode(childTokens);
+    }
+  }
+}
+
+async function highlightToken(token) {
+  try {
+    return await codeToHtml(token.text, {
+      lang: normalizeLanguage(token.lang),
+      themes: {
+        light: "github-light",
+        dark: "github-dark",
+      },
+      defaultColor: false,
+    });
+  } catch {
+    return codeToHtml(token.text, {
+      lang: "text",
+      themes: {
+        light: "github-light",
+        dark: "github-dark",
+      },
+      defaultColor: false,
+    });
+  }
+}
+
+function normalizeLanguage(lang) {
+  const value = lang?.trim().split(/\s+/)[0].toLowerCase() || "text";
+  if (value === "njk") return "html";
+  if (value === "sh" || value === "shell") return "bash";
+  return value;
+}
+
+function nestedTokenLists(token) {
+  const lists = [];
+  if (token.tokens) lists.push(token.tokens);
+  if (token.items) lists.push(...token.items.flatMap((item) => (item.tokens ? [item.tokens] : [])));
+  if (token.rows) lists.push(...token.rows.flatMap((cell) => (cell.tokens ? [cell.tokens] : [])));
+  if (token.header) lists.push(...token.header.flatMap((cell) => (cell.tokens ? [cell.tokens] : [])));
+  return lists;
+}
+
+function plainText(tokens) {
+  return tokens
+    .map((token) => {
+      if (token.tokens) return plainText(token.tokens);
+      return token.text ?? token.raw ?? "";
+    })
+    .join("");
+}
+
+function tokensText(tokens) {
+  return tokens
+    .map((token) => {
+      const childTokens = [];
+      if (token.tokens) childTokens.push(token.tokens);
+      if (token.items) childTokens.push(...token.items.flatMap((item) => (item.tokens ? [item.tokens] : [])));
+      if (token.rows) childTokens.push(...token.rows.flatMap((row) => row.flatMap((cell) => (cell.tokens ? [cell.tokens] : []))));
+      if (token.header) childTokens.push(...token.header.flatMap((cell) => (cell.tokens ? [cell.tokens] : [])));
+      return childTokens.length ? childTokens.map(tokensText).join(" ") : token.text || "";
+    })
+    .join(" ")
+    .replace(/\s+/g, " ")
+    .trim();
+}

package/src/runtime/lib/html.js

@@ -0,0 +1,20 @@
+export function escapeHtml(value) {
+  return String(value ?? "")
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+export function attrs(values = {}) {
+  return Object.entries(values)
+    .filter(([, value]) => value !== undefined && value !== null && value !== false)
+    .map(([key, value]) => (value === true ? ` ${key}` : ` ${key}="${escapeHtml(value)}"`))
+    .join("");
+}
+
+export function addSvgClass(svg, className) {
+  if (!svg || !className) return svg || "";
+  if (svg.includes('class="')) return svg.replace('class="', `class="${className} `);
+  return svg.replace("<svg", `<svg class="${escapeHtml(className)}"`);
+}

package/src/runtime/lib/macros.js

@@ -0,0 +1,180 @@
+import Search from "lucide-static/icons/search.svg?raw";
+import { attrs, escapeHtml } from "./html.js";
+
+export function renderSidebar({
+  id = "sidebar",
+  label = "Sidebar navigation",
+  open = true,
+  side = "left",
+  header = "",
+  footer = "",
+  menu = [],
+  contentAttrs = { class: "scrollbar" },
+} = {}) {
+  return `<aside${attrs({
+    id,
+    class: "sidebar",
+    "data-side": side,
+    "aria-hidden": open ? "false" : "true",
+    inert: open ? undefined : true,
+  })}>
+  <nav aria-label="${escapeHtml(label)}">
+    ${header ? `<header>${header}</header>` : ""}
+    <section${attrs(contentAttrs)}>${renderSidebarContent(menu, `${id}-content`)}</section>
+    ${footer ? `<footer>${footer}</footer>` : ""}
+  </nav>
+</aside>`;
+}
+
+export function renderSidebarContent(items = [], parentIdPrefix = "content") {
+  return items
+    .map((item, index) => {
+      const itemId = `${parentIdPrefix}-${index + 1}`;
+
+      if (item.type === "group") {
+        const groupLabelId = item.id || `group-label-${itemId}`;
+        return `<div role="group"${item.label ? attrs({ "aria-labelledby": groupLabelId }) : ""}${attrs(item.attrs)}>
+  ${item.label ? `<h3 id="${escapeHtml(groupLabelId)}">${escapeHtml(item.label)}</h3>` : ""}
+  <ul>${renderSidebarContent(item.items || [], itemId)}</ul>
+</div>`;
+      }
+
+      if (item.type === "separator") return `<hr role="separator" />`;
+
+      if (item.type === "submenu") {
+        const submenuId = `submenu-${itemId}`;
+        return `<li>
+  <details${attrs({ id: submenuId, open: item.open ? true : undefined, ...without(item.attrs, ["open"]) })}>
+    <summary aria-controls="${escapeHtml(submenuId)}-content">
+      ${item.icon || ""}
+      <span>${escapeHtml(item.label)}</span>
+    </summary>
+    <ul id="${escapeHtml(submenuId)}-content">${renderSidebarContent(item.items || [], itemId)}</ul>
+  </details>
+</li>`;
+      }
+
+      return `<li>
+  <a${attrs({ href: item.url, "aria-current": item.current ? "page" : undefined, ...without(item.attrs, ["href", "aria-current"]) })}>
+    ${item.icon || ""}
+    <span>${escapeHtml(item.label)}</span>
+  </a>
+</li>`;
+    })
+    .join("");
+}
+
+export function renderCommandDialog({
+  id = "command-search",
+  items = [],
+  placeholder = "Search the docs...",
+  emptyText = "No results found.",
+  open = false,
+  commandAttrs = {},
+} = {}) {
+  return `<dialog${attrs({
+    id,
+    class: "command-dialog",
+    "aria-label": "Command menu",
+    open: open ? true : undefined,
+    onclick: "if (event.target === this) this.close()",
+  })}>
+  <div${attrs({ ...commandAttrs, class: ["command", commandAttrs.class].filter(Boolean).join(" ") })}>
+    <header>
+      ${Search}
+      <input${attrs({
+        type: "text",
+        id: `${id}-input`,
+        placeholder,
+        autocomplete: "off",
+        autocorrect: "off",
+        spellcheck: "false",
+        "aria-autocomplete": "list",
+        role: "combobox",
+        "aria-expanded": "true",
+        "aria-controls": `${id}-menu`,
+      })}>
+    </header>
+    <div${attrs({
+      role: "menu",
+      id: `${id}-menu`,
+      "aria-orientation": "vertical",
+      "data-empty": emptyText,
+      class: "scrollbar",
+    })}>${renderCommandItems(items, `${id}-items`)}</div>
+  </div>
+</dialog>`;
+}
+
+export function renderCommandItems(items = [], parentIdPrefix = "items") {
+  return items
+    .map((item, index) => {
+      const itemId = `${parentIdPrefix}-${index + 1}`;
+      if (item.type === "group") {
+        const groupLabelId = item.id || `group-label-${itemId}`;
+        return `<div role="group" aria-labelledby="${escapeHtml(groupLabelId)}"${attrs(item.attrs)}>
+  <span role="heading" id="${escapeHtml(groupLabelId)}">${escapeHtml(item.label)}</span>
+  ${renderCommandItems(item.items || [], itemId)}
+</div>`;
+      }
+
+      if (item.type === "separator") return `<hr role="separator" />`;
+
+      const commonAttrs = {
+        id: itemId,
+        role: "menuitem",
+        "data-keywords": item.keywords,
+        "aria-disabled": item.disabled ? "true" : undefined,
+        ...without(item.attrs, ["href"]),
+      };
+
+      if (item.url) {
+        return `<a${attrs({ ...commonAttrs, href: item.url })}>${item.icon || ""}<span>${escapeHtml(item.label)}</span></a>`;
+      }
+
+      return `<div${attrs(commonAttrs)}>${item.icon || ""}<span>${escapeHtml(item.label)}</span></div>`;
+    })
+    .join("");
+}
+
+export function renderDropdownMenu({ id = "dropdown-menu", trigger = "", items = [], triggerAttrs = {}, popoverAttrs = {} } = {}) {
+  return `<div id="${escapeHtml(id)}" class="dropdown-menu">
+  <button${attrs({
+    type: "button",
+    id: `${id}-trigger`,
+    "aria-haspopup": "menu",
+    "aria-controls": `${id}-menu`,
+    "aria-expanded": "false",
+    ...triggerAttrs,
+  })}>${trigger}</button>
+  <div${attrs({ id: `${id}-popover`, "data-popover": true, "aria-hidden": "true", ...popoverAttrs })}>
+    <div role="menu" id="${escapeHtml(id)}-menu" aria-labelledby="${escapeHtml(id)}-trigger">
+      ${renderDropdownItems(items, `${id}-items`)}
+    </div>
+  </div>
+</div>`;
+}
+
+export function renderDropdownItems(items = [], parentIdPrefix = "items") {
+  return items
+    .map((item, index) => {
+      const itemId = `${parentIdPrefix}-${index + 1}`;
+      if (item.type === "separator") return `<hr role="separator" />`;
+      if (item.type === "group") {
+        const groupLabelId = item.id || `group-label-${itemId}`;
+        return `<div role="group" aria-labelledby="${escapeHtml(groupLabelId)}"${attrs(item.attrs)}>
+  <div role="heading" id="${escapeHtml(groupLabelId)}">${escapeHtml(item.label)}</div>
+  ${renderDropdownItems(item.items || [], itemId)}
+</div>`;
+      }
+      if (item.url) {
+        return `<a${attrs({ id: itemId, role: "menuitem", href: item.url, ...without(item.attrs, ["href"]) })}>${item.icon || ""}${escapeHtml(item.label)}</a>`;
+      }
+      return `<div${attrs({ id: itemId, role: "menuitem", ...item.attrs })}>${item.icon || ""}${escapeHtml(item.label)}</div>`;
+    })
+    .join("");
+}
+
+function without(value = {}, keys = []) {
+  return Object.fromEntries(Object.entries(value || {}).filter(([key]) => !keys.includes(key)));
+}

package/src/runtime/lib/paths.js

@@ -0,0 +1,22 @@
+export const stripSlashes = (value) => String(value || "").replace(/^\/+|\/+$/g, "");
+
+export const routePath = (routeBase, slug) => {
+  const base = stripSlashes(routeBase);
+  const normalizedSlug = slug === "index" ? "" : stripSlashes(slug);
+  const parts = [base, normalizedSlug].filter(Boolean);
+  return parts.length ? `/${parts.join("/")}/` : "/";
+};
+
+export const routeSlug = (slug) => (slug === "index" ? undefined : slug);
+
+export const markdownPath = (routeBase, slug) => {
+  const base = stripSlashes(routeBase);
+  const normalizedSlug = stripSlashes(slug || "index");
+  return `/${[base, `${normalizedSlug}.md`].filter(Boolean).join("/")}`;
+};
+
+export const routeFilePath = (routeBase, file) => {
+  const base = stripSlashes(routeBase);
+  const normalizedFile = stripSlashes(file);
+  return `/${[base, normalizedFile].filter(Boolean).join("/")}`;
+};

package/src/runtime/lib/site.js

@@ -0,0 +1,26 @@
+import fs from "node:fs";
+
+export const defaultSite = {
+  title: "ReallySimpleDocs",
+  description: "A really simple documentation site.",
+  url: "",
+  links: [],
+};
+
+export function getSite(config) {
+  let fileSite = {};
+
+  if (config.siteFile) {
+    try {
+      fileSite = JSON.parse(fs.readFileSync(config.siteFile, "utf8")) || {};
+    } catch {
+      fileSite = {};
+    }
+  }
+
+  return {
+    ...defaultSite,
+    ...fileSite,
+    ...(config.site || {}),
+  };
+}

package/src/runtime/pages/doc.astro

@@ -0,0 +1,20 @@
+---
+import config from "virtual:reallysimpledocs/config";
+import DocsLayout from "../components/DocsLayout.astro";
+import { getPages, renderDoc } from "../lib/docs.js";
+import { routeSlug } from "../lib/paths.js";
+
+export function getStaticPaths() {
+  return getPages(config).map((page) => ({
+    params: { slug: routeSlug(page.slug) },
+    props: { page },
+  }));
+}
+
+const { page } = Astro.props;
+const doc = await renderDoc(config, page);
+---
+
+<DocsLayout page={page} headings={doc.headings}>
+  <Fragment set:html={doc.html} />
+</DocsLayout>

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

@@ -0,0 +1,20 @@
+import config from "virtual:reallysimpledocs/config";
+import { getLlmDocs } from "../lib/docs.js";
+import { getSite } from "../lib/site.js";
+
+export function GET({ site }) {
+  const siteData = getSite(config);
+  const siteUrl = site?.toString().replace(/\/$/, "") || siteData.url || "";
+  const lines = [];
+
+  getLlmDocs(config).forEach((doc) => {
+    lines.push(`# ${doc.title}`, `Source: ${siteUrl}${doc.path}`, "");
+    lines.push(doc.content, "", "---", "");
+  });
+
+  return new Response(lines.join("\n"), {
+    headers: {
+      "content-type": "text/plain; charset=utf-8",
+    },
+  });
+}

package/src/runtime/pages/llms.txt.ts

@@ -0,0 +1,34 @@
+import config from "virtual:reallysimpledocs/config";
+import { flattenMenuSlugs, getLlmDocs, getManifest } from "../lib/docs.js";
+import { getSite } from "../lib/site.js";
+
+export function GET({ site }) {
+  const manifest = getManifest(config);
+  const docs = getLlmDocs(config);
+  const bySlug = new Map(docs.map((doc) => [doc.slug, doc]));
+  const siteData = getSite(config);
+  const siteUrl = site?.toString().replace(/\/$/, "") || siteData.url || "";
+  const lines = [`# ${siteData.title}`, "", "## Docs", ""];
+
+  (manifest.menu || []).forEach((group) => {
+    if (group?.type !== "group") return;
+    lines.push(`### ${group.label || "Docs"}`, "");
+
+    const addSlug = (slug) => {
+      const doc = bySlug.get(slug);
+      if (!doc) return;
+      const url = `${siteUrl}${doc.path}`;
+      lines.push(`- [${doc.title}](${url})`);
+    };
+
+    flattenMenuSlugs([group]).forEach(addSlug);
+
+    lines.push("");
+  });
+
+  return new Response(lines.join("\n"), {
+    headers: {
+      "content-type": "text/plain; charset=utf-8",
+    },
+  });
+}

package/src/runtime/pages/markdown.ts

@@ -0,0 +1,17 @@
+import config from "virtual:reallysimpledocs/config";
+import { getMarkdownExport, getPages } from "../lib/docs.js";
+
+export function getStaticPaths() {
+  return getPages(config).map((page) => ({
+    params: { slug: page.slug },
+    props: { page },
+  }));
+}
+
+export function GET({ props }) {
+  return new Response(getMarkdownExport(config, props.page), {
+    headers: {
+      "content-type": "text/markdown; charset=utf-8",
+    },
+  });
+}