serve-my-md 1.1.0

package/README.md

@@ -0,0 +1,52 @@
+# serve-my-md
+
+A tiny CLI to generate a static docs website from markdown files.
+
+## Documentation
+
+Full docs are at [https://ashishantil.dev/serve-my-md](https://ashishantil.dev/serve-my-md).
+
+## Basic usage
+
+```bash
+serve-my-md --directory .
+```
+
+Run this inside (or pointing to) the folder that contains your markdown docs.
+
+## Commands and options
+
+- `serve-my-md`: scans markdown files, builds the static site, and outputs it in the target directory.
+- `-d, --directory <path>`: sets the docs root directory (default: current directory).
+- `-i, --interactive`: asks for directory input interactively.
+
+## Optional customization
+
+In your target docs directory, you can optionally create files like `smm.config.json` and `.smmignore` to customize behavior (routing, sorting, ignored paths, etc.).
+
+## Features
+
+- **Static site generation** — every page is a standalone `.html` file with pre-rendered content
+- **Groupers** — directory-based sidebar grouping with `(Name)` syntax, excluded from URLs
+- **Full-text search** — site-wide search with `Ctrl+Shift+F`
+- **Keyboard shortcuts** — quick page navigation
+- **Light/dark themes** — automatic or user-toggleable
+- **Responsive** — works on desktop and mobile
+- **Accessibility** — keyboard navigation, ARIA labels, semantic landmarks
+- **Breadcrumbs** — clear navigation context
+- **Custom ordering** — numeric filename prefixes with `trimIndexFromPath` config
+- **Rich markdown** — footnotes, task lists, syntax highlighting
+- **SEO** — per-page OG tags, meta descriptions, pre-rendered content
+- **Font customization** — configurable title/body/mono fonts
+- **Public assets** — copy static files via `publicPath` config
+
+## Future goals
+
+- **Search Indexing** — structured search index for smarter results
+- **Config validation** — Zod-based schema validation of `smm.config.json` with JSON Schema export
+- **Sitemap** — automatic `sitemap.xml` generation
+- **Per-page Open Graph** — page-level og tags from frontmatter
+- **Doctor command** — health checks: config validation, route discovery, broken link detection, and more
+- **Link validation** — flag invalid internal links at build-time
+- **Optional RSS** — config-enableable RSS feed for blog/changelog content
+- **SchemaStore upload** — publish JSON Schema to SchemaStore once stable

package/bin/index.js

@@ -0,0 +1,487 @@
+#!/usr/bin/env node
+
+// cli/src/lib/logger.ts
+var Logger = class {
+  static log(message, type) {
+    console.log(`${type ? `[${type.toUpperCase()}] ` : ""}${message}`);
+  }
+  static error(message) {
+    console.error(`[ERROR] ${message}`);
+  }
+};
+
+// cli/src/shared.ts
+import MarkdownIt from "markdown-it";
+import path2 from "path";
+import Prism from "prismjs";
+
+// cli/src/core/index.ts
+import fs2 from "fs/promises";
+import path from "path";
+import { minimatch } from "minimatch";
+
+// cli/src/utils/index.ts
+import fs from "fs/promises";
+var indexTokens = "1234567890.";
+function trimIndexFromPath(filePath) {
+  return filePath.split("/").map((segment) => {
+    let offset = 0;
+    let encountered = false;
+    while (offset < segment.length && (indexTokens.includes(segment[offset]) || segment[offset] === " " && !encountered))
+      if (segment[offset++] !== " ") encountered = true;
+    return segment.slice(offset).trim();
+  }).join("/");
+}
+function cleanName(filename) {
+  return filename === "index.md" ? "" : filename.replace(/\.md$/, "");
+}
+function optional(prop, val) {
+  return val ? { [prop]: val } : {};
+}
+function slugify(filepath) {
+  return filepath.toLowerCase().split("").map((c) => {
+    if (".,;\"'\\:<>`?!".includes(c)) return "";
+    if (c === " " || c === "_") return "-";
+    return c;
+  }).join("");
+}
+async function FileOrDirectoryExists(filepath) {
+  try {
+    await fs.access(filepath);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function makeRoutesOfNestedPaths(nestedPaths, prefix = "/") {
+  return nestedPaths.reduce((acc, { pathSegment, children, isGrouper }) => {
+    return [
+      ...acc,
+      ...isGrouper || !children ? [] : [prefix + pathSegment],
+      ...children ? makeRoutesOfNestedPaths(
+        children,
+        prefix + (!isGrouper ? pathSegment + "/" : "")
+      ) : isGrouper ? [] : [prefix + pathSegment]
+    ];
+  }, []);
+}
+function makeRoutesOfNestedPathsRaw(nestedPaths, prefix = "/") {
+  return nestedPaths.reduce((acc, { pathSegment, children }) => {
+    return [
+      ...acc,
+      ...children ? makeRoutesOfNestedPathsRaw(
+        children,
+        prefix + pathSegment + "/"
+      ) : [prefix + pathSegment]
+    ];
+  }, []);
+}
+function ogToHtml(og) {
+  const tags = [];
+  for (const [key, value] of Object.entries(og)) {
+    if (value == null) continue;
+    if (["images", "videos", "audios"].includes(key)) continue;
+    if (Array.isArray(value)) {
+      for (const v of value) {
+        tags.push(`<meta property="og:${key}" content="${v}">`);
+      }
+    } else {
+      tags.push(`<meta property="og:${key}" content="${value}">`);
+    }
+  }
+  [...og.images ?? [], ...og.videos ?? [], ...og.audios ?? []].forEach(
+    (img) => {
+      Object.entries(img).forEach(([k, v]) => {
+        if (v == null) return;
+        tags.push(`<meta property="og:${k}" content="${v}">`);
+      });
+    }
+  );
+  return tags.join("\n");
+}
+
+// cli/src/lib/commander.ts
+import * as inquirer from "@inquirer/prompts";
+
+// cli/src/config.json
+var config_default = {
+  name: "serve-my-md",
+  version: "1.0.0",
+  description: "A CLI tool to create a ready-to-serve static website from markdown files",
+  defaultConfigPath: "./smm.config.json",
+  defaultIgnorePath: "./.smmignore"
+};
+
+// cli/src/lib/commander.ts
+import { Command } from "commander";
+var program = new Command();
+program.name(config_default.name).description(config_default.description).version(config_default.version);
+program.option("-d, --directory <path>", "Directory to scan for markdown files", ".");
+program.option("-i, --interactive", "Enable interactive mode");
+if (process.env.VITEST) {
+  program.option("--skip-build", "Skip the build step");
+}
+program.parse(process.argv);
+var options = program.opts();
+if (options.interactive || options.directory === void 0) {
+  const res = await inquirer.input({
+    message: `Enter root directory: `,
+    default: options.directory || "./"
+  });
+  options.directory = res.trim();
+}
+
+// cli/src/core/index.ts
+import { readdirSync } from "fs";
+
+// shared/constants.json
+var constants_default = {
+  STATIC_TEMP_CONTENT_PREFIX: "__smm_static_temp_content__"
+};
+
+// cli/src/core/index.ts
+var STATIC_TEMP_CONTENT_PREFIX = constants_default.STATIC_TEMP_CONTENT_PREFIX;
+async function readConfig(filepath) {
+  try {
+    const data = JSON.parse(await fs2.readFile(filepath, "utf-8"));
+    return data;
+  } catch (err) {
+    Logger.log(
+      `No config file found at ${filepath}, proceeding with defaults.`,
+      "info"
+    );
+    return {};
+  }
+}
+async function parseSmmIgnore(filePath) {
+  try {
+    let shouldIgnore3 = function(targetPath) {
+      const p = targetPath.replace(/\\/g, "/");
+      let ignored = false;
+      for (const rule of rules) {
+        if (minimatch(p, rule.pattern, { dot: true })) {
+          ignored = !rule.negated;
+        }
+      }
+      return ignored;
+    };
+    var shouldIgnore2 = shouldIgnore3;
+    const raw = await fs2.readFile(filePath, "utf8");
+    const rules = raw.split(/\r?\n/).map((line) => line.trim()).filter((line) => line !== "" && !line.startsWith("#")).map((line) => {
+      const negated = line.startsWith("!");
+      const pattern = negated ? line.slice(1) : line;
+      return { pattern, negated };
+    });
+    return { rules, shouldIgnore: shouldIgnore3 };
+  } catch (err) {
+    Logger.log(
+      `No .smmignore file found at ${filePath}, proceeding without ignore rules.`,
+      "info"
+    );
+    return {
+      rules: [],
+      shouldIgnore: (_) => false
+    };
+  }
+}
+async function getMarkdownFiles(baseUrl, pairChildren) {
+  const files = await fs2.readdir(baseUrl, { withFileTypes: true });
+  const routeTree = pairChildren || [];
+  const promises = [];
+  for (const file of files) {
+    const filePath = path.join(baseUrl, file.name);
+    if (shouldIgnore(filePath.slice(options.directory.length)) || filePath.slice(options.directory.length) === finalConfig.publicPath)
+      continue;
+    if (file.isDirectory()) {
+      const isGrouper = file.name.startsWith("(") && file.name.endsWith(")");
+      const dirPair = {
+        label: isGrouper ? file.name.slice(1, -1) : file.name,
+        children: [],
+        pathSegment: file.name,
+        isGrouper
+      };
+      routeTree.push(dirPair);
+      promises.push(
+        getMarkdownFiles(filePath, dirPair.children)
+      );
+    } else if (file.name.endsWith(".md")) {
+      routeTree.push({
+        label: file.name,
+        children: null,
+        pathSegment: file.name
+      });
+      promises.push(Promise.resolve([filePath]));
+    }
+  }
+  if (finalConfig.sortRoutes)
+    routeTree.sort((a, b) => {
+      if (a.label === "index.md") return -1;
+      if (b.label === "index.md") return 1;
+      if (a.isGrouper && !b.isGrouper) return 1;
+      if (b.isGrouper && !a.isGrouper) return -1;
+      return a.label.localeCompare(b.label);
+    });
+  const filess = finalConfig.trimIndexFromPath ? (await Promise.all(promises)).flat().map((val) => trimIndexFromPath(val)) : (await Promise.all(promises)).flat();
+  return pairChildren ? filess : { routeTree, files: filess };
+}
+function cleanNestedPaths(routeTree) {
+  for (const pair of routeTree) {
+    if (finalConfig.trimIndexFromPath) {
+      pair.label = trimIndexFromPath(pair.label);
+    }
+    pair.label = cleanName(pair.label);
+    pair.pathSegment = getPath(cleanName(pair.pathSegment)).replaceAll("/", "");
+    if (pair.children) {
+      cleanNestedPaths(pair.children);
+      if (pair.children?.length === 1 && ["", "index.md"].includes(pair.children?.[0]?.label)) {
+        pair.children = null;
+      }
+    }
+  }
+}
+function getPath(filepath) {
+  let transformedPath = filepath.replace(options.directory, "").replace(/\\/g, "/").replace(/\/index.md$/, "").replace(/\.md$/, "");
+  if (finalConfig.trimIndexFromPath) {
+    transformedPath = trimIndexFromPath(transformedPath);
+  }
+  return slugify(transformedPath).split("/").filter((s) => !(s.startsWith("(") && s.endsWith(")"))).join("/") || "/";
+}
+async function parseMD(filepath) {
+  const path4 = getPath(filepath);
+  return {
+    path: path4,
+    content: mdParser.render(await fs2.readFile(filepath, "utf-8"))
+  };
+}
+async function generateHtml(distDir, routeContent) {
+  try {
+    let htmlTemplate = await fs2.readFile(
+      path.join(import.meta.dirname, "..", "index.html"),
+      "utf-8"
+    );
+    const commentStart = htmlTemplate.indexOf("<!--");
+    htmlTemplate = htmlTemplate.replace(
+      htmlTemplate.slice(
+        commentStart,
+        htmlTemplate.indexOf("-->", commentStart) + 3
+      ),
+      ""
+    );
+    if (distDir) {
+      const files = readdirSync(path.join(distDir, "assets"));
+      const cssFile = files.find((file) => file.endsWith(".css"));
+      const jsFile = files.find((file) => file.endsWith(".js"));
+      const prefix = distDir.slice(path.join(import.meta.dirname, options.directory).length);
+      htmlTemplate = htmlTemplate.replace(`<script type="module" src="/src/main.tsx"></script>`, "");
+      if (cssFile && jsFile) {
+        htmlTemplate = htmlTemplate.replace(
+          "{{distAssets}}",
+          `<link rel="stylesheet" href="${path.join(
+            prefix,
+            "assets",
+            cssFile
+          )}" />
+             <script type="module" src="${path.join(
+            prefix,
+            "assets",
+            jsFile
+          )}"></script>`
+        );
+      } else {
+        Logger.error(`Could not find CSS and JS files in dist assets.`);
+        htmlTemplate = htmlTemplate.replace("{{distAssets}}", "");
+      }
+    } else {
+      htmlTemplate = htmlTemplate.replace("{{distAssets}}", "");
+    }
+    return htmlTemplate.replace("{{og}}", ogToHtml(finalConfig.og ?? {})).replace("{{title}}", finalConfig.rootTitle ?? "Serve My MD").replace("{{description}}", finalConfig.description ?? "").replace(
+      "{{favicon}}",
+      finalConfig.favicon ? `<link rel="icon" href="${finalConfig.favicon}" />` : ""
+    ).replace(
+      "{{fonts}}",
+      finalConfig.fonts ? (finalConfig.fonts.title && finalConfig.fonts.title.url ? `<link rel="stylesheet" href="${finalConfig.fonts.title.url}" />` : "") + (finalConfig.fonts.body && finalConfig.fonts.body.url ? `<link rel="stylesheet" href="${finalConfig.fonts.body.url}" />` : "") + (finalConfig.fonts.mono && finalConfig.fonts.mono.url ? `<link rel="stylesheet" href="${finalConfig.fonts.mono.url}" />` : "") : ""
+    ).replace("{{content}}", STATIC_TEMP_CONTENT_PREFIX + (routeContent ?? "")).trim();
+  } catch (err) {
+    throw new Error(`Failed to generate HTML: ${err}`);
+  }
+}
+async function buildDistRoutesFromRouteTree(routeTree, groupedRoutes, distPath, prefix = "/") {
+  for (const node of routeTree) {
+    if (node.children && node.isGrouper) {
+      await buildDistRoutesFromRouteTree(
+        node.children,
+        groupedRoutes,
+        distPath,
+        prefix
+      );
+    } else {
+      const distRoutePath = path.join(distPath, prefix, node.pathSegment.replace("/", "")) + (node.pathSegment === "" ? "/index.html" : ".html");
+      await fs2.mkdir(path.dirname(distRoutePath), { recursive: true });
+      const html = await generateHtml(
+        distPath,
+        groupedRoutes[path.posix.join(prefix, node.pathSegment)]?.[0]?.content
+      );
+      await fs2.writeFile(distRoutePath, html, "utf-8");
+      if (node.children) {
+        await buildDistRoutesFromRouteTree(
+          node.children,
+          groupedRoutes,
+          distPath,
+          path.join(prefix, node.pathSegment)
+        );
+      }
+    }
+  }
+}
+
+// cli/src/smm.config.json
+var smm_config_default = {
+  rootTitle: "Serve My MD",
+  description: "A simple markdown to static site builder.",
+  baseRoute: "/",
+  defaultTheme: "dark",
+  markdownItOptions: {
+    html: true,
+    xhtmlOut: true,
+    breaks: true,
+    langPrefix: "language-",
+    linkify: true,
+    typographer: false
+  },
+  outDir: "dist",
+  favicon: "",
+  logo: "",
+  name: "Serve My MD",
+  showNameWithLogo: true,
+  sortRoutes: true,
+  trimIndexFromPath: false
+};
+
+// cli/src/shared.ts
+import MarkdownItFootNote from "markdown-it-footnote";
+import MarkdownItTasks from "markdown-it-task-lists";
+import loadLanguages from "prismjs/components/index.js";
+var { shouldIgnore } = await parseSmmIgnore(
+  path2.join(options.directory, config_default.defaultIgnorePath)
+);
+var finalConfig = {
+  ...smm_config_default,
+  ...await readConfig(path2.join(options.directory, config_default.defaultConfigPath))
+};
+var md = new MarkdownIt({
+  ...finalConfig.markdownItOptions,
+  highlight: function(str, lang) {
+    if (!Object.hasOwn(Prism.languages, lang)) {
+      loadLanguages([lang]);
+    }
+    const highlighted = Prism.highlight(str, Prism.languages[lang], lang);
+    return `<pre class="language-${lang}"><code class="language-${lang}">${highlighted}</code></pre>`;
+  }
+}).use(MarkdownItFootNote).use(MarkdownItTasks);
+md.linkify.set({ fuzzyEmail: false });
+var mdParser = md;
+
+// cli/src/core/build.ts
+import { cp, rm, writeFile } from "fs/promises";
+import path3, { resolve } from "path";
+import { fileURLToPath } from "url";
+import { build as viteBuild } from "vite";
+import { mkdirSync } from "fs";
+var DIST_DIRNAME = finalConfig.outDir || "dist";
+var WEB_DIRNAME = "web";
+var PUBLIC_DIRNAME = "public";
+async function build(options2) {
+  const skipBuild = ("skipBuild" in options2 && options2.skipBuild) ?? false;
+  const { routeTree, files: markdownFiles } = await getMarkdownFiles(
+    options2.directory
+  );
+  const parsePromises = [];
+  Logger.log("Processing routes...");
+  for (const file of makeRoutesOfNestedPathsRaw(routeTree)) {
+    parsePromises.push(parseMD(path3.join(options2.directory, file)));
+  }
+  cleanNestedPaths(routeTree);
+  const groupedRoutes = Object.groupBy(
+    await Promise.all(parsePromises),
+    (route) => route.path
+  );
+  const routes = makeRoutesOfNestedPaths(routeTree).reduce(
+    (acc, pth) => [...acc, ...(groupedRoutes[pth] ?? []).map((r) => ({ ...r, path: path3.join(finalConfig.baseRoute || "/", r.path) }))],
+    []
+  );
+  const out = {
+    rootTitle: finalConfig.rootTitle ?? "Documentation",
+    description: finalConfig.description ?? "Documentation",
+    baseRoute: finalConfig.baseRoute ?? "/",
+    defaultTheme: finalConfig.defaultTheme ?? "dark",
+    name: finalConfig.name ?? "Serve My MD",
+    showNameWithLogo: finalConfig.showNameWithLogo ?? false,
+    routes,
+    outDir: DIST_DIRNAME,
+    fonts: {
+      title: finalConfig.fonts?.title?.name || "serif",
+      body: finalConfig.fonts?.body?.name || "sans-serif",
+      mono: finalConfig.fonts?.mono?.name || "monospace"
+    },
+    ...optional("favicon", finalConfig.favicon),
+    ...optional("version", finalConfig.version)
+  };
+  routes.forEach((o) => {
+    Logger.log(o.path);
+  });
+  const __dirname = path3.dirname(fileURLToPath(import.meta.url));
+  const webDir = path3.join(__dirname, "..", WEB_DIRNAME);
+  const distDir = path3.join(webDir, DIST_DIRNAME);
+  mkdirSync(path3.join(webDir, "src", ".generated"), { recursive: true });
+  await writeFile(
+    path3.join(webDir, "src", ".generated", "output.json"),
+    JSON.stringify(out)
+  );
+  await writeFile(
+    path3.join(webDir, "src", ".generated", "paths.json"),
+    JSON.stringify(routeTree)
+  );
+  Logger.log("\nParsed MDs");
+  await writeFile(path3.join(webDir, "index.html"), await generateHtml());
+  Logger.log("Generated HTML from template");
+  if (!skipBuild) {
+    if (finalConfig.publicPath) {
+      if (await FileOrDirectoryExists(
+        path3.join(options2.directory, finalConfig.publicPath)
+      )) {
+        Logger.log(`Copying public assets from ${finalConfig.publicPath}...`);
+        await cp(
+          path3.join(options2.directory, finalConfig.publicPath),
+          path3.join(webDir, PUBLIC_DIRNAME),
+          { recursive: true }
+        );
+      } else {
+        Logger.error(`Public path "${finalConfig.publicPath}" does not exist!`);
+      }
+    }
+    Logger.log("Building the app...");
+    await viteBuild({
+      configFile: resolve(webDir, "vite.config.ts")
+    });
+    await buildDistRoutesFromRouteTree(routeTree, groupedRoutes, distDir);
+    const targetDist = path3.join(options2.directory, DIST_DIRNAME);
+    await rm(targetDist, { recursive: true }).catch(() => {
+    });
+    Logger.log("Built the app, copying results...");
+    return cp(distDir, targetDist, { recursive: true }).then(() => {
+      Logger.log("Done successfully!");
+      return true;
+    }).catch((err) => {
+      Logger.error("Error copying files: " + err);
+      return false;
+    });
+  }
+  return Promise.resolve(true);
+}
+
+// cli/src/index.ts
+if (await build(options)) {
+  Logger.log("Completed successfully.");
+} else {
+  Logger.error("Failed.");
+}

package/index.html

@@ -0,0 +1,70 @@
+<!-- ? this html file is a template for that final site 
+
+     ? The `content` field is only for SEO purpose, and is obviously overriden on mount by react 
+     ? `distAssets` is for the css and js files generated by vite. Only used for the sub-routes, not for the home page.
+     ? The `loading` class on body is for the loading screen, and is removed on mount by react.
+-->
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    {{favicon}}
+    <meta name="theme-color" content="#000000" />
+    <meta
+    name="description"
+      content="{{description}}"
+      />
+    {{fonts}}
+    {{og}}
+    <title>{{title}}</title>
+    {{distAssets}}
+    
+    <style>
+      @keyframes keep-rotating {
+        from {
+          transform: translate(-50%, -50%) rotate(0deg);
+        }
+        to {
+          transform: translate(-50%, -50%) rotate(360deg);
+        }
+      }
+
+      body.loading {
+        overflow: hidden;
+
+        &::before {
+          content: '';
+          position: fixed;
+          inset: 0;
+          z-index: 50;
+          display: flex;
+          align-items: center;
+          justify-content: center;
+          background-color: rgba(255, 255, 255, 0.8);
+          backdrop-filter: blur(4px);
+        }
+
+        &::after {
+          content: '';
+          position: fixed;
+          width: 4rem;
+          height: 4rem;
+          top: 50%;
+          left: 50%;
+          transform: translate(-50%, -50%);
+          z-index: 51;
+          border: 4px solid #3498db;
+          border-top-color: transparent;
+          border-radius: 50%;
+          animation: keep-rotating 1s linear infinite;
+        }
+      }
+    </style>
+  </head>
+  <body class='loading'>
+    <div id="app">{{content}}</div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>