seemore 1.8.7 → 1.9.0

package/README.md

@@ -81,9 +81,9 @@ Typical use cases include:
 - **Full MDX** — when Markdown isn't enough, `.mdx` pages take real JSX: your own React components, inline SVG, custom classes and CSS; `<Callout>`, `<Card>`, `<CodeBlockTabs>` and friends come built in, with no imports to write
 - **Static export** — `seemore build` prerenders every page to its own HTML file, `404.html` included, and adds the conventions individual hosts look for (`_redirects`, `200.html`, `.nojekyll`)
 - **Search built in** — static, zero-setup full-text search out of the box, with shareable highlighted results; [Algolia](https://algolia.com) and [Orama Cloud](https://orama.com) for hosted indexes
+- **Page actions** — an Actions button on every page: export the page as one self-contained HTML file or print it to PDF, with the CLI equivalent in `seemore export <file>`
 - **12 themes** — dark and light follow the system, with a toggle that remembers your choice; your own CSS always wins
 - **Rich Markdown** — GitHub Flavoured Markdown, admonitions, steps, `[[wikilinks]]`, [Mermaid](https://mermaid.js.org) and [D2](https://d2lang.com) diagrams, click-to-zoom images, embedded PDFs
-- **First-class code blocks** — build-time [Shiki](https://shiki.style) highlighting in the theme's own colours, with titles, line numbers, diff markers and focus
 - **Editor integration** — one extension covers VS Code, Cursor, Antigravity and other VS Code-compatible editors, remote workspaces included
 
 ## View in your browser
@@ -147,6 +147,16 @@ The result is a `dist/` folder of plain web files: drop it on [Netlify](https://
 > [!TIP]
 > Project sites on GitHub Pages live under `username.github.io/my-repo/`, not the root, so set `base` once: `base: '/my-repo/'` (or `--base /my-repo/` on the CLI). Building under GitHub Actions without it set prints the exact line to add.
 
+## Export page
+
+An **Actions** button above every page exports just that page. **Export as HTML** writes one self-contained file — styles inlined, images embedded, diagrams kept — that opens offline from a double-click, ready to drop into Slack, email or an AI chat. The CLI produces the same HTML file without a browser:
+
+```bash
+npx seemore export docs/spec.md   # writes spec.html next to the Markdown
+```
+
+Which actions appear — or whether the button exists at all — is one line of config, `pageActions`. See [Configuration](#configuration) and the [features page](https://arifszn.github.io/seemore/features) for the details.
+
 ## Configuration
 
 Optional — a folder with no config file builds correctly everywhere. To adjust things, create `seemore.config.ts` next to your content:
@@ -165,6 +175,7 @@ export default {
   footer: { text: '© 2026' },
   editLink: { base: 'https://github.com/you/repo/edit/main/docs' },
   search: 'static', // or { provider: 'orama-cloud', endpoint, apiKey } / { provider: 'algolia', appId, apiKey, indexName }
+  pageActions: ['export-html', 'export-pdf'],
   exclude: ['drafts/**'],
 };
 ```
@@ -319,6 +330,7 @@ Pages are ordered by:
 ```
 seemore [dir]           start the dev server
 seemore build [dir]     build a static site into dist/
+seemore export <file>   export a page as a standalone HTML file
 
 Options
   --port <number>        dev server port (default 4040)
@@ -326,7 +338,7 @@ Options
   --open / --no-open     open a browser on start (default: no)
   --json                 print one machine-readable JSON line instead of the summary (dev only)
   --config <path>        path to seemore.config.ts
-  --out <dir>            build output directory (default: dist)
+  --out <dir>            build output directory (default: dist); for export, where the HTML file is written
   --base <path>          subpath the site is served from, e.g. /my-repo/
   -h, --help             show this message
   -v, --version          show the version

package/dist/cli/index.js

@@ -72,7 +72,7 @@ var init_paths = __esm({
 
 // src/cli/index.ts
 import { parseArgs } from "util";
-import pc4 from "picocolors";
+import pc5 from "picocolors";
 
 // src/cli/build.ts
 import { mkdirSync as mkdirSync3, mkdtempSync, readFileSync as readFileSync5, rmSync, writeFileSync as writeFileSync5 } from "fs";
@@ -130,6 +130,7 @@ var FEATURES = [
   "search.highlight",
   "social.cards"
 ];
+var ACTION_IDS = ["export-html", "export-pdf"];
 
 // src/node/config/features.ts
 var FEATURE_DEFAULTS = {
@@ -246,6 +247,7 @@ var searchSchema = z.union([
     indexName: z.string()
   })
 ]);
+var pageActionsSchema = z.array(z.enum(ACTION_IDS)).default(["export-html", "export-pdf"]);
 var configSchema = z.object({
   /**
    * Optional here, but required whenever a config file exists — load.ts enforces that,
@@ -271,6 +273,7 @@ var configSchema = z.object({
     text: z.string().default("Edit this page")
   }).optional(),
   search: searchSchema.default("static"),
+  pageActions: pageActionsSchema,
   exclude: z.array(z.string()).default([])
 });
 
@@ -296,6 +299,7 @@ function resolveConfig(input, options) {
     footer: parsed.footer,
     editLink: parsed.editLink,
     search,
+    pageActions: parsed.pageActions,
     exclude: parsed.exclude,
     root: options.root,
     configFile: options.configFile
@@ -393,8 +397,8 @@ function slugifySegment(segment) {
 function toRoute(file) {
   const posix = toPosix(file);
   const segments = posix.split("/");
-  const basename2 = segments.pop() ?? "";
-  const stem = basename2.replace(CONTENT_EXT, "");
+  const basename3 = segments.pop() ?? "";
+  const stem = basename3.replace(CONTENT_EXT, "");
   const isIndex = INDEX_NAMES.has(stem.toLowerCase());
   const slugs = segments.map(slugifySegment);
   if (!isIndex) slugs.push(slugifySegment(stem));
@@ -460,10 +464,10 @@ function createLinkResolver(pages, base) {
       const dir = withoutExt.split("/").slice(0, -1).join("/");
       if (dir !== "") byPath.set(dir.toLowerCase(), page);
     }
-    const basename2 = withoutExt.split("/").pop() ?? "";
-    add(byName, basename2.toLowerCase(), page);
-    const slugged = slugifySegment(basename2);
-    if (slugged !== basename2.toLowerCase()) add(byName, slugged, page);
+    const basename3 = withoutExt.split("/").pop() ?? "";
+    add(byName, basename3.toLowerCase(), page);
+    const slugged = slugifySegment(basename3);
+    if (slugged !== basename3.toLowerCase()) add(byName, slugged, page);
   }
   const pick = (candidates) => [...candidates].sort((a, b) => {
     const depth = a.file.split("/").length - b.file.split("/").length;
@@ -523,9 +527,9 @@ function splitHash(value) {
   if (index === -1) return [value, void 0];
   return [value.slice(0, index), value.slice(index + 1)];
 }
-function joinPosix(fromDir, relative3) {
+function joinPosix(fromDir, relative4) {
   const segments = [...fromDir];
-  for (const part of toPosix(relative3).split("/")) {
+  for (const part of toPosix(relative4).split("/")) {
     if (part === "" || part === ".") continue;
     if (part === "..") segments.pop();
     else segments.push(part);
@@ -1387,6 +1391,7 @@ function clientConfig(ctx) {
     nav: config.nav,
     footer: config.footer,
     editLink: config.editLink,
+    pageActions: config.pageActions,
     favicon: config.favicon === void 0 ? void 0 : withBase(config.base, `/${toPosix(config.favicon)}`),
     search: config.search.provider === "static" ? { provider: "static", from: withBase(config.base, "/api/search.json") } : config.search,
     contentRoot: config.root
@@ -1625,10 +1630,10 @@ async function loadPrerenderModule(ctx, ssrOutDir) {
   await build(createViteConfig({ ctx, mode: "build", ssrOutDir }));
   const entry = join6(ssrOutDir, "entry.prerender.js");
   const loaded = await import(pathToFileURL(entry).href);
-  if (typeof loaded.render !== "function" || typeof loaded.listRoutes !== "function") {
-    throw new Error(`seemore: the prerender build at ${entry} did not export \`render\` and \`listRoutes\`.`);
+  if (typeof loaded.render !== "function" || typeof loaded.renderArticle !== "function" || typeof loaded.listRoutes !== "function") {
+    throw new Error(`seemore: the prerender build at ${entry} did not export \`render\`, \`renderArticle\` and \`listRoutes\`.`);
   }
-  return { render: loaded.render, listRoutes: loaded.listRoutes };
+  return { render: loaded.render, renderArticle: loaded.renderArticle, listRoutes: loaded.listRoutes };
 }
 
 // src/node/social/cards.ts
@@ -1838,12 +1843,248 @@ async function runDev(options) {
   };
 }
 
+// src/cli/export.ts
+import { existsSync as existsSync4, mkdtempSync as mkdtempSync2, readFileSync as readFileSync6, readdirSync, rmSync as rmSync2, statSync, writeFileSync as writeFileSync6, mkdirSync as mkdirSync4 } from "fs";
+import { basename as basename2, dirname as dirname8, extname, join as join9, relative as relative3, resolve as resolve6 } from "path";
+import { tmpdir as tmpdir3 } from "os";
+import pc4 from "picocolors";
+import { build as viteBuild2 } from "vite";
+init_paths();
+
+// src/app/export/themeToggle.ts
+var THEME_TOGGLE = `<button type="button" class="seemore-export-theme-toggle" aria-label="Toggle dark mode">
+<svg class="seemore-icon-light" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><circle cx="12" cy="12" r="4"/><path d="M12 2v2"/><path d="M12 20v2"/><path d="m4.93 4.93 1.41 1.41"/><path d="m17.66 17.66 1.41 1.41"/><path d="M2 12h2"/><path d="M20 12h2"/><path d="m6.34 17.66-1.41 1.41"/><path d="m19.07 4.93-1.41 1.41"/></svg>
+<svg class="seemore-icon-dark" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12 3a6 6 0 0 0 9 9 9 9 0 1 1-9-9Z"/></svg>
+</button>`;
+
+// src/cli/export.ts
+async function runExport(options) {
+  const target = resolve6(options.cwd, options.file);
+  if (!existsSync4(target) || !statSync(target).isFile()) {
+    throw new Error(`No such file: ${options.file}`);
+  }
+  const contentRoot = resolveContentRoot(options.cwd, dirname8(target));
+  const loaded = await loadConfig({ root: contentRoot, configPath: resolveConfigPath(options) });
+  const config = {
+    ...loaded.config,
+    base: options.base === void 0 ? loaded.config.base : normaliseBase(options.base)
+  };
+  if (!config.pageActions.includes("export-html")) {
+    throw new Error(`\`pageActions\` in ${loaded.file ?? "seemore.config.ts"} does not include 'export-html', so this site's pages cannot be exported.`);
+  }
+  const ctx = createContext({ config, contentRoot });
+  const scan2 = ctx.source.current();
+  for (const warning of scan2.warnings) ctx.warnings.add(warning);
+  const errors = ctx.errors();
+  if (errors.length > 0) {
+    throw new Error(`seemore found ${errors.length} problem(s) in ${contentRoot}:
+
+${errors.join("\n\n")}`);
+  }
+  const page = ctx.pages().find((candidate) => candidate.absPath === canonicalise(target));
+  if (page === void 0) {
+    throw new Error(`${options.file} is not part of this site \u2014 excluded in the config, or outside ${relative3(options.cwd, contentRoot) || "."}.`);
+  }
+  const outDir = mkdtempSync2(join9(tmpdir3(), "seemore-export-"));
+  const ssrOutDir = mkdtempSync2(join9(tmpdir3(), "seemore-export-ssr-"));
+  try {
+    await viteBuild2(createViteConfig({ ctx, mode: "build", outDir }));
+    const css = readBuiltCss(outDir);
+    const template = readFileSync6(join9(outDir, "index.html"), "utf8");
+    const prerender = await loadPrerenderModule(ctx, ssrOutDir);
+    const article = await prerender.renderArticle(page.url);
+    const runtime = await bundleRuntime();
+    const html = assemble({ article, css, runtime, config, outDir, contentRoot, template });
+    const filename = `${basename2(target).replace(/\.(?:md|mdx)$/i, "")}.html`;
+    const targetPath = options.out === void 0 ? join9(dirname8(target), filename) : join9(resolve6(options.cwd, options.out), filename);
+    if (existsSync4(targetPath)) {
+      console.log(pc4.yellow(`seemore  replacing existing ${relative3(options.cwd, targetPath) || targetPath}`));
+    }
+    mkdirSync4(dirname8(targetPath), { recursive: true });
+    writeFileSync6(targetPath, html, "utf8");
+    ctx.warnings.flush();
+    console.log(pc4.green(`seemore  wrote ${relative3(options.cwd, targetPath) || targetPath} (${formatBytes2(html.length)})`));
+  } finally {
+    rmSync2(outDir, { recursive: true, force: true });
+    rmSync2(ssrOutDir, { recursive: true, force: true });
+  }
+}
+function readBuiltCss(outDir) {
+  const assets = join9(outDir, "assets");
+  const files = existsSync4(assets) ? readdirSync(assets).filter((file) => file.endsWith(".css")) : [];
+  if (files.length === 0) throw new Error("The build produced no stylesheet \u2014 the export would be unstyled.");
+  return files.map((file) => readFileSync6(join9(assets, file), "utf8")).join("\n");
+}
+async function bundleRuntime() {
+  const dir = mkdtempSync2(join9(tmpdir3(), "seemore-export-runtime-"));
+  try {
+    await viteBuild2({
+      configFile: false,
+      root: appRoot(),
+      build: {
+        outDir: dir,
+        emptyOutDir: true,
+        minify: true,
+        target: "es2018",
+        lib: {
+          entry: join9(appRoot(), "export", "standalone.ts"),
+          name: "seemoreExport",
+          formats: ["iife"],
+          fileName: () => "runtime.js"
+        }
+      }
+    });
+    return readFileSync6(join9(dir, "runtime.js"), "utf8");
+  } finally {
+    rmSync2(dir, { recursive: true, force: true });
+  }
+}
+function assemble(input) {
+  const { article, css, runtime, config, outDir, contentRoot, template } = input;
+  const content = withExportToc(inlineHtmlAssets(article.html, config.base, outDir, contentRoot));
+  const title = article.title === "" ? config.title : `${article.title} \xB7 ${config.title}`;
+  const description = article.description ?? config.description;
+  const favicon = faviconLink(config, contentRoot, template);
+  return [
+    "<!doctype html>",
+    '<html lang="en">',
+    "<head>",
+    '<meta charset="utf-8">',
+    '<meta name="viewport" content="width=device-width, initial-scale=1">',
+    `<title>${escapeHtml(title)}</title>`,
+    description === void 0 ? "" : `<meta name="description" content="${escapeHtml(description)}">`,
+    '<meta name="generator" content="seemore">',
+    favicon,
+    `<style>
+${inlineCssUrls(css, config.base, outDir, contentRoot).replaceAll("</style", "<\\/style")}</style>`,
+    "</head>",
+    "<body>",
+    `<main class="seemore-export-main">`,
+    `<article class="seemore-article prose">${content}</article>`,
+    "</main>",
+    THEME_TOGGLE,
+    `<script>${runtime.replaceAll("</script", "<\\/script")}</script>`,
+    "</body>",
+    "</html>"
+  ].filter((line) => line !== "").join("\n");
+}
+function inlineHtmlAssets(html, base, outDir, contentRoot) {
+  return html.replace(
+    /(<(?:img|embed|iframe|video|audio|source)\b[^>]*\bsrc=")([^"]*)(")/g,
+    (whole, open, src, close) => {
+      const file = resolveAsset(src, base, outDir, contentRoot);
+      if (file === void 0) return whole;
+      try {
+        return `${open}${dataUriFor(file)}${close}`;
+      } catch {
+        return whole;
+      }
+    }
+  );
+}
+function inlineCssUrls(css, base, outDir, contentRoot) {
+  return css.replace(/url\(\s*(['"]?)([^'")]+)\1\s*\)/g, (whole, _quote, raw) => {
+    if (/^(?:data:|https?:)/i.test(raw)) return whole;
+    const file = resolveAsset(raw, base, outDir, contentRoot);
+    if (file === void 0) return whole;
+    try {
+      return `url("${dataUriFor(file)}")`;
+    } catch {
+      return whole;
+    }
+  });
+}
+function resolveAsset(src, base, outDir, contentRoot) {
+  if (src === "" || /^(?:data:|blob:)/i.test(src) || src.startsWith("#")) return void 0;
+  let path = src.split("#")[0]?.split("?")[0] ?? "";
+  if (base !== "/" && path.startsWith(base)) path = path.slice(base.length - 1);
+  const suffix = path.replace(/^\/+/, "");
+  for (const root of [outDir, contentRoot]) {
+    const candidate = join9(root, suffix);
+    if (existsSync4(candidate) && statSync(candidate).isFile()) return candidate;
+  }
+  return void 0;
+}
+var MIME = {
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".ico": "image/x-icon",
+  ".pdf": "application/pdf",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm"
+};
+function dataUriFor(file) {
+  const mime = MIME[extname(file).toLowerCase()] ?? "application/octet-stream";
+  return `data:${mime};base64,${readFileSync6(file).toString("base64")}`;
+}
+function faviconLink(config, contentRoot, template) {
+  if (config.favicon !== void 0) {
+    const file = join9(contentRoot, config.favicon);
+    if (existsSync4(file)) {
+      try {
+        return `<link rel="icon" href="${dataUriFor(file)}" />`;
+      } catch {
+      }
+    }
+  }
+  const matches = Array.from(template.matchAll(/<link rel="icon"[^>]*>/gi));
+  return matches.at(-1)?.[0] ?? "";
+}
+function withExportToc(html) {
+  const headings = Array.from(html.matchAll(/<h([23])\b[^>]*\bid="([^"]*)"[^>]*>([\s\S]*?)<\/h\1>/g)).map(
+    (match) => ({
+      depth: Number(match[1]),
+      id: match[2] ?? "",
+      text: decodeEntities((match[3] ?? "").replace(/<[^>]+>/g, ""))
+    })
+  );
+  if (headings.length === 0) return html;
+  const sections = [];
+  for (const heading of headings) {
+    if (heading.depth === 2 || sections.length === 0) {
+      sections.push({ id: heading.id, text: heading.text, children: [] });
+    } else {
+      sections.at(-1)?.children.push({ id: heading.id, text: heading.text });
+    }
+  }
+  const items = sections.map((section) => {
+    const self = `<a href="#${section.id}">${escapeHtml(section.text)}</a>`;
+    if (section.children.length === 0) return `<li>${self}</li>`;
+    const kids = section.children.map((child) => `<li><a href="#${child.id}">${escapeHtml(child.text)}</a></li>`).join("");
+    return `<li>${self}<ul>${kids}</ul></li>`;
+  }).join("");
+  const toc = `<nav class="seemore-export-toc"><details><summary>On this page</summary><ul>${items}</ul></details></nav>`;
+  const h1 = /<\/h1>/i.exec(html);
+  return h1 === null ? toc + html : html.slice(0, h1.index + h1[0].length) + toc + html.slice(h1.index + h1[0].length);
+}
+function decodeEntities(text) {
+  return text.replaceAll("&amp;", "&").replaceAll("&lt;", "<").replaceAll("&gt;", ">").replaceAll("&quot;", '"').replaceAll("&#39;", "'");
+}
+function escapeHtml(value) {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll('"', "&quot;");
+}
+function formatBytes2(size) {
+  if (size < 1024) return `${size} B`;
+  if (size < 1024 * 1024) return `${(size / 1024).toFixed(1)} kB`;
+  return `${(size / (1024 * 1024)).toFixed(1)} MB`;
+}
+
 // src/cli/index.ts
 var USAGE = `
-${pc4.bold("seemore")} \u2014 turn a folder of Markdown into a docs site
+${pc5.bold("seemore")} \u2014 turn a folder of Markdown into a docs site
 
   seemore [dir]           start the dev server
   seemore build [dir]     build a static site into dist/
+  seemore export <file>   export a page as a standalone HTML file
 
 Options
   --port <number>        dev server port (default 4040)
@@ -1851,7 +2092,7 @@ Options
   --open / --no-open     open a browser on start (default: no)
   --json                 print one machine-readable JSON line instead of the summary (dev only)
   --config <path>        path to seemore.config.ts
-  --out <dir>            build output directory (default: dist)
+  --out <dir>            build output directory (default: dist); for export, where the HTML file is written
   --base <path>          subpath the site is served from, e.g. /my-repo/
   -h, --help             show this message
   -v, --version          show the version
@@ -1885,21 +2126,28 @@ async function main(argv = process.argv.slice(2)) {
     return;
   }
   if (values.version === true) {
-    const { readFileSync: readFileSync6 } = await import("fs");
-    const { join: join9 } = await import("path");
+    const { readFileSync: readFileSync7 } = await import("fs");
+    const { join: join10 } = await import("path");
     const { packageRoot: packageRoot2 } = await Promise.resolve().then(() => (init_paths(), paths_exports));
-    const pkg = JSON.parse(readFileSync6(join9(packageRoot2(), "package.json"), "utf8"));
+    const pkg = JSON.parse(readFileSync7(join10(packageRoot2(), "package.json"), "utf8"));
     console.log(pkg.version);
     return;
   }
   const [command, ...rest] = positionals;
   const isBuild = command === "build";
+  const isExport = command === "export";
   const dir = isBuild ? rest[0] : command;
   const shared = { cwd: process.cwd(), dir, configPath: values.config, base: values.base };
   if (isBuild) {
     await runBuild({ ...shared, outDir: values.out });
     return;
   }
+  if (isExport) {
+    const file = rest[0];
+    if (file === void 0) throw new Error("Usage: seemore export <file> \u2014 name the Markdown file to export.");
+    await runExport({ cwd: shared.cwd, file, out: values.out, configPath: values.config, base: values.base });
+    return;
+  }
   await runDev({
     ...shared,
     port: values.port === void 0 ? void 0 : Number(values.port),
@@ -1910,7 +2158,7 @@ async function main(argv = process.argv.slice(2)) {
 }
 main().catch((error) => {
   console.error(`
-${pc4.red("seemore")} ${error instanceof Error ? error.message : String(error)}
+${pc5.red("seemore")} ${error instanceof Error ? error.message : String(error)}
 `);
   process.exitCode = 1;
 });