@ayushshanker/mdo 0.1.0

package/README.md

@@ -0,0 +1,102 @@
+# @ayushshanker/mdo
+
+`@ayushshanker/mdo` is the npm package name. It installs the `mdo` CLI for previewing Markdown files and folders in your browser.
+
+## Install
+
+Global install:
+
+```bash
+npm install -g @ayushshanker/mdo
+```
+
+One-off usage without installing:
+
+```bash
+npx @ayushshanker/mdo README.md
+pnpm dlx @ayushshanker/mdo README.md
+yarn dlx @ayushshanker/mdo README.md
+```
+
+## Command Name
+
+The package is published as `@ayushshanker/mdo`, but the executable command is:
+
+```bash
+mdo
+```
+
+## Usage
+
+Open the current directory in folder mode:
+
+```bash
+mdo
+```
+
+Open a specific Markdown file:
+
+```bash
+mdo README.md
+```
+
+Open a folder on a fixed port:
+
+```bash
+mdo docs --port 3000
+```
+
+Export a Markdown file to HTML instead of opening the browser:
+
+```bash
+mdo README.md --output README.html
+```
+
+Use a theme:
+
+```bash
+mdo README.md --theme earthsong
+mdo README.md --theme gruvbox
+mdo README.md --dark
+```
+
+## Modes
+
+### File Mode
+
+When you pass a Markdown file, `mdo` renders it to HTML.
+
+Examples:
+
+```bash
+mdo README.md
+mdo docs/intro.markdown
+mdo README.md --output README.html
+```
+
+### Folder Mode
+
+When you pass a directory, `mdo` starts a local preview server and opens a directory listing in your browser.
+
+Examples:
+
+```bash
+mdo .
+mdo docs
+mdo docs --port 3000
+```
+
+## Flags
+
+- `--dark` uses the GitHub dark theme
+- `--theme <name>` selects `github`, `github-dark`, `sepia`, `earth`, `earthsong`, `gruvbox`, or `dracula`
+- `--output <file>` writes HTML to disk instead of opening the browser; file mode only
+- `--port <port>` uses a fixed port for folder mode
+- `--help` prints usage information
+- `--version` prints the package version
+
+## Notes
+
+- `mdo` with no path is the same as `mdo .`
+- `--output` only works for file mode
+- Folder mode binds to loopback only and is intended for local preview

package/bin/mdo.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+const { runCli } = require("../lib/cli");
+
+runCli().catch((error) => {
+  const message = error && error.message ? error.message : String(error);
+  process.stderr.write(`${message}\n`);
+  process.exitCode = 1;
+});

package/lib/cli.js

@@ -0,0 +1,116 @@
+"use strict";
+
+const fs = require("node:fs/promises");
+const path = require("node:path");
+const { Command } = require("commander");
+const packageJson = require("../package.json");
+const { runFileMode } = require("./file-mode");
+const { runFolderMode } = require("./folder-mode");
+const { THEMES } = require("./renderer");
+const {
+  ensureFileIsReadableMarkdown,
+  validatePort
+} = require("./utils");
+
+function resolveThemeOption(options) {
+  if (options.theme) {
+    if (!Object.hasOwn(THEMES, options.theme)) {
+      throw new Error(`Theme must be one of: ${Object.keys(THEMES).join(", ")}.`);
+    }
+    return options.theme;
+  }
+
+  return options.dark ? "github-dark" : "github";
+}
+
+function buildProgram() {
+  const program = new Command();
+
+  program
+    .name("mdo")
+    .description("Open markdown files or folders in your browser.")
+    .version(packageJson.version, "--version", "Print package version and exit.")
+    .argument("[target]", "Markdown file or folder to open.", ".")
+    .option("--dark", "Use GitHub dark theme.")
+    .option(
+      "--theme <name>",
+      `Use a named theme: ${Object.keys(THEMES).join(", ")}.`
+    )
+    .option("--output <file>", "Write HTML to a file instead of opening the browser.")
+    .option("--port <port>", "Use a fixed port for folder mode.", validatePort)
+    .addHelpText(
+      "after",
+      `
+Examples:
+  npx mdopen
+  npx mdopen README.md
+  npx mdopen README.md --theme dracula
+  mdo
+  mdo .
+  mdo README.md
+  mdo docs --port 3000
+`
+    );
+
+  return program;
+}
+
+async function runCli(argv = process.argv) {
+  const program = buildProgram();
+  program.exitOverride();
+
+  let parsed;
+  try {
+    parsed = program.parse(argv, { from: "node" });
+  } catch (error) {
+    if (typeof error.exitCode === "number") {
+      process.exitCode = error.exitCode;
+      if (
+        error.code !== "commander.helpDisplayed" &&
+        error.code !== "commander.version"
+      ) {
+        process.stderr.write(`${error.message}\n`);
+      }
+      return;
+    }
+    throw error;
+  }
+
+  const options = parsed.opts();
+  const themeName = resolveThemeOption(options);
+  const targetPath = path.resolve(parsed.args[0] || ".");
+  const cwdRealPath = await fs.realpath(process.cwd());
+  const stats = await fs.stat(targetPath).catch(() => null);
+
+  if (!stats) {
+    throw new Error("Path does not exist.");
+  }
+
+  if (stats.isDirectory()) {
+    if (options.output) {
+      throw new Error("--output is only supported for file mode.");
+    }
+    await runFolderMode({
+      directoryPath: targetPath,
+      fixedPort: options.port,
+      themeName
+    });
+    return;
+  }
+
+  if (options.port !== undefined) {
+    throw new Error("--port is only supported for folder mode.");
+  }
+
+  await ensureFileIsReadableMarkdown(targetPath);
+  await runFileMode({
+    cwdRealPath,
+    filePath: targetPath,
+    outputPath: options.output ? path.resolve(options.output) : undefined,
+    themeName
+  });
+}
+
+module.exports = {
+  runCli
+};

package/lib/constants.js

@@ -0,0 +1,32 @@
+"use strict";
+
+const path = require("node:path");
+
+const MAX_FILE_SIZE_BYTES = 10 * 1024 * 1024;
+const MIN_PORT = 20001;
+const MAX_PORT = 30000;
+const PORT_RETRIES = 3;
+const LOOPBACK_HOST = "127.0.0.1";
+const MERMAID_VERSION = "11.12.0";
+const MERMAID_CDN_URL = `https://cdn.jsdelivr.net/npm/mermaid@${MERMAID_VERSION}/dist/mermaid.min.js`;
+const LIGHT_HLJS_THEME = "github.css";
+const DARK_HLJS_THEME = "github-dark.css";
+const GITHUB_MARKDOWN_CSS = "github-markdown.css";
+const GITHUB_MARKDOWN_DARK_CSS = "github-markdown-dark.css";
+const DEFAULT_ARTICLE_TITLE = "Markdown Preview";
+const PACKAGE_ROOT = path.resolve(__dirname, "..");
+
+module.exports = {
+	DARK_HLJS_THEME,
+	DEFAULT_ARTICLE_TITLE,
+	GITHUB_MARKDOWN_CSS,
+	GITHUB_MARKDOWN_DARK_CSS,
+	LIGHT_HLJS_THEME,
+	LOOPBACK_HOST,
+	MAX_FILE_SIZE_BYTES,
+	MAX_PORT,
+	MERMAID_CDN_URL,
+	MIN_PORT,
+	PACKAGE_ROOT,
+	PORT_RETRIES
+};

package/lib/file-mode.js

@@ -0,0 +1,40 @@
+"use strict";
+
+const fs = require("node:fs/promises");
+const path = require("node:path");
+const open = require("open");
+const { renderMarkdownFile } = require("./renderer");
+const {
+  humanUrlPath,
+  tempHtmlPath,
+  writeUtf8File
+} = require("./utils");
+
+async function runFileMode({ filePath, outputPath, cwdRealPath, themeName }) {
+  const { html } = await renderMarkdownFile(filePath, {
+    themeName,
+    title: path.basename(filePath)
+  });
+
+  if (outputPath) {
+    await writeUtf8File(outputPath, html);
+    return { outputPath, opened: false };
+  }
+
+  const htmlPath = tempHtmlPath(cwdRealPath, filePath);
+  await fs.mkdir(path.dirname(htmlPath), { recursive: true });
+  await writeUtf8File(htmlPath, html);
+
+  try {
+    await open(htmlPath);
+  } catch (error) {
+    process.stderr.write(`Browser open failed. File available at ${htmlPath}\n`);
+    throw new Error(`Failed to open browser for ${humanUrlPath(cwdRealPath, filePath)}.`);
+  }
+
+  return { outputPath: htmlPath, opened: true };
+}
+
+module.exports = {
+  runFileMode
+};

package/lib/folder-mode.js

@@ -0,0 +1,229 @@
+"use strict";
+
+const http = require("node:http");
+const fs = require("node:fs/promises");
+const path = require("node:path");
+const open = require("open");
+const { LOOPBACK_HOST, MAX_PORT, MIN_PORT, PORT_RETRIES } = require("./constants");
+const { renderDirectoryListing, renderMarkdownFile } = require("./renderer");
+const { isMarkdownPath, toPosixPath } = require("./utils");
+
+async function resolveInsideRoot(rootRealPath, requestPath) {
+  const normalized = decodeURIComponent(requestPath || "/");
+  const candidatePath = path.resolve(rootRealPath, `.${normalized}`);
+  const candidateRelativePath = path.relative(rootRealPath, candidatePath);
+
+  if (candidateRelativePath.startsWith("..") || path.isAbsolute(candidateRelativePath)) {
+    return { type: "forbidden", candidatePath };
+  }
+
+  let realCandidatePath;
+
+  try {
+    realCandidatePath = await fs.realpath(candidatePath);
+  } catch (error) {
+    return { type: "missing", candidatePath };
+  }
+
+  const relativePath = path.relative(rootRealPath, realCandidatePath);
+  if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+    return { type: "forbidden", candidatePath: realCandidatePath };
+  }
+
+  return { type: "ok", realPath: realCandidatePath };
+}
+
+async function buildDirectoryEntries(rootRealPath, realDirectoryPath, requestPath) {
+  const children = await fs.readdir(realDirectoryPath, { withFileTypes: true });
+  const visibleEntries = [];
+
+  for (const child of children) {
+    if (child.name.startsWith(".")) {
+      continue;
+    }
+
+    const absolutePath = path.join(realDirectoryPath, child.name);
+    let realChildPath;
+    try {
+      realChildPath = await fs.realpath(absolutePath);
+    } catch {
+      continue;
+    }
+
+    const relativeToRoot = path.relative(rootRealPath, realChildPath);
+    if (relativeToRoot.startsWith("..") || path.isAbsolute(relativeToRoot)) {
+      continue;
+    }
+
+    const isDirectory = child.isDirectory();
+    const isFile = child.isFile();
+
+    if (!isDirectory && !(isFile && isMarkdownPath(child.name))) {
+      continue;
+    }
+
+    const baseHref = requestPath.endsWith("/") ? requestPath : `${requestPath}/`;
+    visibleEntries.push({
+      href: `${baseHref}${encodeURIComponent(child.name)}${isDirectory ? "/" : ""}`,
+      name: child.name,
+      type: isDirectory ? "directory" : "file"
+    });
+  }
+
+  return visibleEntries.sort((left, right) => {
+    if (left.type !== right.type) {
+      return left.type === "directory" ? -1 : 1;
+    }
+    return left.name.localeCompare(right.name);
+  });
+}
+
+function parentHrefFor(requestPath) {
+  if (requestPath === "/") {
+    return null;
+  }
+  const trimmed = requestPath.endsWith("/") ? requestPath.slice(0, -1) : requestPath;
+  const parentPath = path.posix.dirname(trimmed);
+  return parentPath === "/" ? "/" : `${parentPath}/`;
+}
+
+function chooseRandomPort() {
+  return Math.floor(Math.random() * (MAX_PORT - MIN_PORT + 1)) + MIN_PORT;
+}
+
+function listen(server, port) {
+  return new Promise((resolve, reject) => {
+    server.once("error", reject);
+    server.listen(port, LOOPBACK_HOST, () => {
+      server.off("error", reject);
+      resolve();
+    });
+  });
+}
+
+async function startServerWithRetries(server, fixedPort) {
+  let lastError;
+  const attempts = fixedPort ? 1 : PORT_RETRIES;
+
+  for (let index = 0; index < attempts; index += 1) {
+    const port = fixedPort || chooseRandomPort();
+    try {
+      await listen(server, port);
+      return port;
+    } catch (error) {
+      lastError = error;
+      if (fixedPort) {
+        throw new Error(`Port ${fixedPort} is unavailable.`);
+      }
+    }
+  }
+
+  throw new Error(lastError ? "Failed to start preview server." : "Failed to choose a port.");
+}
+
+function sendHtml(response, statusCode, html) {
+  response.writeHead(statusCode, {
+    "content-type": "text/html; charset=utf-8",
+    "cache-control": "no-store"
+  });
+  response.end(html);
+}
+
+function sendText(response, statusCode, message) {
+  response.writeHead(statusCode, {
+    "content-type": "text/plain; charset=utf-8",
+    "cache-control": "no-store"
+  });
+  response.end(message);
+}
+
+function installShutdownHandlers(server) {
+  let shuttingDown = false;
+
+  const shutdown = (signal) => {
+    if (shuttingDown) {
+      return;
+    }
+    shuttingDown = true;
+    const timeout = setTimeout(() => {
+      process.exit(0);
+    }, 2000);
+    timeout.unref();
+
+    server.close(() => {
+      clearTimeout(timeout);
+      process.exit(0);
+    });
+  };
+
+  process.on("SIGINT", shutdown);
+  process.on("SIGTERM", shutdown);
+}
+
+async function runFolderMode({ directoryPath, fixedPort, themeName }) {
+  const rootRealPath = await fs.realpath(directoryPath);
+  const server = http.createServer(async (request, response) => {
+    try {
+      const requestPath = (request.url || "/").split("?")[0] || "/";
+      const resolved = await resolveInsideRoot(rootRealPath, requestPath);
+
+      if (resolved.type === "forbidden") {
+        sendText(response, 403, "Forbidden");
+        return;
+      }
+
+      if (resolved.type === "missing") {
+        sendText(response, 404, "Not found");
+        return;
+      }
+
+      const stats = await fs.stat(resolved.realPath);
+
+      if (stats.isDirectory()) {
+        const entries = await buildDirectoryEntries(rootRealPath, resolved.realPath, requestPath);
+        const html = renderDirectoryListing({
+          directoryName: path.basename(rootRealPath),
+          entries,
+          themeName,
+          parentHref: parentHrefFor(requestPath),
+          requestPath
+        });
+        sendHtml(response, 200, html);
+        return;
+      }
+
+      if (!isMarkdownPath(resolved.realPath)) {
+        sendText(response, 404, "Not found");
+        return;
+      }
+
+      const parentHref = parentHrefFor(requestPath);
+      const { html } = await renderMarkdownFile(resolved.realPath, {
+        themeName,
+        title: path.basename(resolved.realPath),
+        backHref: parentHref,
+        backLabel: "Back"
+      });
+      sendHtml(response, 200, html);
+    } catch {
+      sendText(response, 500, "Internal server error");
+    }
+  });
+
+  const port = await startServerWithRetries(server, fixedPort);
+  installShutdownHandlers(server);
+
+  const url = `http://${LOOPBACK_HOST}:${port}/`;
+  try {
+    await open(url);
+  } catch {
+    process.stderr.write(`Browser open failed. Server available at ${url}\n`);
+    throw new Error("Failed to open browser.");
+  }
+
+  return { port, rootRealPath, url, server };
+}
+
+module.exports = {
+  runFolderMode
+};

package/lib/renderer.js

@@ -0,0 +1,357 @@
+"use strict";
+
+const fs = require("node:fs");
+const fsp = require("node:fs/promises");
+const path = require("node:path");
+const MarkdownIt = require("markdown-it");
+const markdownItAnchor = require("markdown-it-anchor");
+const markdownItTaskLists = require("markdown-it-task-lists");
+const hljs = require("highlight.js");
+const {
+  DARK_HLJS_THEME,
+  DEFAULT_ARTICLE_TITLE,
+  GITHUB_MARKDOWN_CSS,
+  GITHUB_MARKDOWN_DARK_CSS,
+  LIGHT_HLJS_THEME,
+  MERMAID_CDN_URL,
+  PACKAGE_ROOT
+} = require("./constants");
+const {
+  ensureFileIsReadableMarkdown,
+  escapeHtml
+} = require("./utils");
+
+function loadCss(relativePath) {
+  const cssPath = require.resolve(relativePath, { paths: [PACKAGE_ROOT] });
+  return fs.readFileSync(cssPath, "utf8");
+}
+
+const markdownCssLight = loadCss(`github-markdown-css/${GITHUB_MARKDOWN_CSS}`);
+const markdownCssDark = loadCss(`github-markdown-css/${GITHUB_MARKDOWN_DARK_CSS}`);
+const hljsCssLight = loadCss(`highlight.js/styles/${LIGHT_HLJS_THEME}`);
+const hljsCssDark = loadCss(`highlight.js/styles/${DARK_HLJS_THEME}`);
+
+function createMarkdownRenderer() {
+  return new MarkdownIt({
+    html: true,
+    linkify: true,
+    highlight(code, language) {
+      if (language && language.toLowerCase() === "mermaid") {
+        return `<pre class="mermaid">${escapeHtml(code)}</pre>`;
+      }
+
+      if (language && hljs.getLanguage(language)) {
+        const highlighted = hljs.highlight(code, { language, ignoreIllegals: true }).value;
+        return `<pre><code class="hljs language-${escapeHtml(language)}">${highlighted}</code></pre>`;
+      }
+
+      return `<pre><code class="hljs">${escapeHtml(code)}</code></pre>`;
+    }
+  })
+    .enable(["table", "strikethrough"])
+    .use(markdownItAnchor)
+    .use(markdownItTaskLists, { enabled: true, label: true, labelAfter: true });
+}
+
+const renderer = createMarkdownRenderer();
+
+const THEMES = {
+  github: {
+    accent: "#0969da",
+    background: "#ffffff",
+    color: "#1f2328",
+    darkMode: false,
+    hljsCss: hljsCssLight,
+    markdownCss: markdownCssLight,
+    mermaidTheme: "default",
+    navFontColor: "#57606a",
+    overlayCss: ""
+  },
+  "github-dark": {
+    accent: "#58a6ff",
+    background: "#0d1117",
+    color: "#c9d1d9",
+    darkMode: true,
+    hljsCss: hljsCssDark,
+    markdownCss: markdownCssDark,
+    mermaidTheme: "dark",
+    navFontColor: "#8b949e",
+    overlayCss: ""
+  },
+  sepia: {
+    accent: "#8b5e34",
+    background: "#f6efe2",
+    color: "#433422",
+    darkMode: false,
+    hljsCss: hljsCssLight,
+    markdownCss: markdownCssLight,
+    mermaidTheme: "neutral",
+    navFontColor: "#6e5a43",
+    overlayCss: `
+body { background-image: linear-gradient(180deg, rgba(139, 94, 52, 0.06), rgba(139, 94, 52, 0)); }
+.markdown-body {
+  color: #433422;
+}
+.markdown-body h1, .markdown-body h2, .markdown-body h3, .markdown-body h4, .markdown-body h5, .markdown-body h6 {
+  color: #2f2418;
+}
+.markdown-body pre, .markdown-body code, .markdown-body blockquote {
+  background-color: rgba(114, 87, 56, 0.08);
+}
+.markdown-body table tr {
+  background-color: rgba(255, 255, 255, 0.35);
+}
+`
+  },
+  earth: {
+    accent: "#8c5a2b",
+    background: "#efe4d0",
+    color: "#39281a",
+    darkMode: false,
+    hljsCss: hljsCssLight,
+    markdownCss: markdownCssLight,
+    mermaidTheme: "neutral",
+    navFontColor: "#6f5840",
+    overlayCss: `
+body { background-image: linear-gradient(135deg, rgba(140, 90, 43, 0.08), rgba(95, 124, 84, 0.06)); }
+.markdown-body {
+  color: #39281a;
+}
+.markdown-body a, .mdo-nav a {
+  color: #8c5a2b;
+}
+.markdown-body h1, .markdown-body h2, .markdown-body h3, .markdown-body h4, .markdown-body h5, .markdown-body h6 {
+  color: #2d1f14;
+}
+.markdown-body pre, .markdown-body code, .markdown-body blockquote {
+  background-color: rgba(115, 84, 52, 0.1);
+}
+.markdown-body hr, .markdown-body table th, .markdown-body table td {
+  border-color: rgba(88, 63, 39, 0.22);
+}
+`
+  },
+  earthsong: {
+    accent: "#b97732",
+    background: "#2a211b",
+    color: "#eadfce",
+    darkMode: true,
+    hljsCss: hljsCssDark,
+    markdownCss: markdownCssDark,
+    mermaidTheme: "dark",
+    navFontColor: "#c6b49f",
+    overlayCss: `
+body { background-image: radial-gradient(circle at top, rgba(185, 119, 50, 0.2), rgba(42, 33, 27, 0) 42%); }
+.markdown-body {
+  color: #eadfce;
+}
+.markdown-body a, .mdo-nav a {
+  color: #d89a51;
+}
+.markdown-body h1, .markdown-body h2, .markdown-body h3, .markdown-body h4, .markdown-body h5, .markdown-body h6 {
+  color: #f2d7b1;
+}
+.markdown-body pre, .markdown-body code, .markdown-body blockquote {
+  background-color: rgba(77, 58, 45, 0.94);
+}
+.markdown-body table tr {
+  background-color: rgba(90, 66, 49, 0.48);
+}
+`
+  },
+  gruvbox: {
+    accent: "#d79921",
+    background: "#282828",
+    color: "#ebdbb2",
+    darkMode: true,
+    hljsCss: hljsCssDark,
+    markdownCss: markdownCssDark,
+    mermaidTheme: "dark",
+    navFontColor: "#d5c4a1",
+    overlayCss: `
+body { background-image: linear-gradient(180deg, rgba(215, 153, 33, 0.08), rgba(40, 40, 40, 0)); }
+.markdown-body {
+  color: #ebdbb2;
+}
+.markdown-body a, .mdo-nav a {
+  color: #d79921;
+}
+.markdown-body h1, .markdown-body h2, .markdown-body h3, .markdown-body h4, .markdown-body h5, .markdown-body h6 {
+  color: #fabd2f;
+}
+.markdown-body pre, .markdown-body code, .markdown-body blockquote {
+  background-color: rgba(60, 56, 54, 0.95);
+}
+.markdown-body table tr {
+  background-color: rgba(80, 73, 69, 0.45);
+}
+`
+  },
+  dracula: {
+    accent: "#bd93f9",
+    background: "#1e1f29",
+    color: "#f8f8f2",
+    darkMode: true,
+    hljsCss: hljsCssDark,
+    markdownCss: markdownCssDark,
+    mermaidTheme: "dark",
+    navFontColor: "#c0b8d8",
+    overlayCss: `
+body { background-image: radial-gradient(circle at top, rgba(189, 147, 249, 0.18), rgba(30, 31, 41, 0) 45%); }
+.markdown-body {
+  color: #f8f8f2;
+}
+.markdown-body a, .mdo-nav a {
+  color: #bd93f9;
+}
+.markdown-body pre, .markdown-body code, .markdown-body blockquote {
+  background-color: rgba(68, 71, 90, 0.95);
+}
+.markdown-body table tr {
+  background-color: rgba(68, 71, 90, 0.45);
+}
+`
+  }
+};
+
+function resolveTheme(themeName) {
+  return THEMES[themeName] || THEMES.github;
+}
+
+function buildStyles(themeName) {
+  const theme = resolveTheme(themeName);
+  const markdownCss = theme.markdownCss;
+  const hljsCss = theme.hljsCss;
+
+  return `
+${markdownCss}
+${hljsCss}
+body {
+  margin: 0;
+  background: ${theme.background};
+  color: ${theme.color};
+}
+.markdown-body {
+  box-sizing: border-box;
+  max-width: 980px;
+  margin: 0 auto;
+  padding: 45px;
+}
+.mdo-nav {
+  max-width: 980px;
+  margin: 0 auto;
+  padding: 24px 45px 0;
+  font: 14px/1.5 -apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif;
+  color: ${theme.navFontColor};
+}
+.mdo-nav a {
+  color: ${theme.accent};
+  text-decoration: none;
+}
+.mdo-nav a:hover {
+  text-decoration: underline;
+}
+@media (max-width: 767px) {
+  .markdown-body {
+    padding: 15px;
+  }
+  .mdo-nav {
+    padding: 15px 15px 0;
+  }
+}
+${theme.overlayCss}
+`;
+}
+
+function buildMermaidBootstrap(themeName) {
+  const theme = resolveTheme(themeName);
+  return `
+<script src="${MERMAID_CDN_URL}"></script>
+<script>
+  mermaid.initialize({ startOnLoad: true, theme: "${theme.mermaidTheme}" });
+</script>`;
+}
+
+function buildDocument({ bodyHtml, themeName, title, backHref, backLabel, hasMermaid }) {
+  const navHtml = backHref
+    ? `<nav class="mdo-nav"><a href="${escapeHtml(backHref)}">&larr; ${escapeHtml(backLabel || "Back")}</a></nav>`
+    : "";
+  const mermaidHtml = hasMermaid ? buildMermaidBootstrap(themeName) : "";
+
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline'; img-src data: https: http:; font-src data: https: http:; script-src 'unsafe-inline' https://cdn.jsdelivr.net; connect-src https://cdn.jsdelivr.net; media-src data: https: http:;">
+    <title>${escapeHtml(title || DEFAULT_ARTICLE_TITLE)}</title>
+    <style>${buildStyles(themeName)}</style>
+  </head>
+  <body>
+    ${navHtml}
+    <article class="markdown-body">
+      ${bodyHtml}
+    </article>
+    ${mermaidHtml}
+  </body>
+</html>`;
+}
+
+async function renderMarkdownFile(filePath, options = {}) {
+  await ensureFileIsReadableMarkdown(filePath);
+  const source = await fsp.readFile(filePath, "utf8");
+  const bodyHtml = renderer.render(source);
+  const title = options.title || path.basename(filePath);
+
+  return {
+    html: buildDocument({
+      bodyHtml,
+      themeName: options.themeName || "github",
+      title,
+      backHref: options.backHref,
+      backLabel: options.backLabel,
+      hasMermaid: /<pre class="mermaid">/.test(bodyHtml)
+    }),
+    title
+  };
+}
+
+function renderDirectoryListing({ directoryName, entries, themeName, requestPath, parentHref }) {
+  const listItems = entries
+    .map((entry) => {
+      const suffix = entry.type === "directory" ? "/" : "";
+      return `<li><a href="${escapeHtml(entry.href)}">${escapeHtml(entry.name + suffix)}</a></li>`;
+    })
+    .join("\n");
+
+  const heading = requestPath === "/" ? directoryName : `${directoryName} · ${requestPath}`;
+  const backHref = parentHref
+    ? `<nav class="mdo-nav"><a href="${escapeHtml(parentHref)}">&larr; Up</a></nav>`
+    : "";
+
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1">
+    <meta http-equiv="Content-Security-Policy" content="default-src 'none'; style-src 'unsafe-inline';">
+    <title>${escapeHtml(heading)}</title>
+    <style>${buildStyles(themeName || "github")}</style>
+  </head>
+  <body>
+    ${backHref}
+    <article class="markdown-body">
+      <h1>${escapeHtml(heading)}</h1>
+      <ul>
+        ${listItems}
+      </ul>
+    </article>
+  </body>
+</html>`;
+}
+
+module.exports = {
+  THEMES,
+  renderDirectoryListing,
+  renderMarkdownFile
+};

package/lib/utils.js

@@ -0,0 +1,92 @@
+"use strict";
+
+const fs = require("node:fs/promises");
+const path = require("node:path");
+const os = require("node:os");
+const crypto = require("node:crypto");
+const {
+  MAX_FILE_SIZE_BYTES,
+  MAX_PORT
+} = require("./constants");
+
+function isMarkdownPath(targetPath) {
+  return /\.(md|markdown)$/i.test(targetPath);
+}
+
+async function ensureFileIsReadableMarkdown(filePath) {
+  const stats = await fs.stat(filePath);
+  if (!stats.isFile()) {
+    throw new Error("Path must be a markdown file.");
+  }
+  if (!isMarkdownPath(filePath)) {
+    throw new Error("Only .md and .markdown files are supported.");
+  }
+  if (stats.size > MAX_FILE_SIZE_BYTES) {
+    throw new Error("Markdown file exceeds the 10 MiB limit.");
+  }
+  return stats;
+}
+
+function validatePort(portValue) {
+  if (portValue === undefined) {
+    return undefined;
+  }
+  const port = Number(portValue);
+  if (!Number.isInteger(port) || port < 1 || port > MAX_PORT) {
+    throw new Error(`Port must be an integer between 1 and ${MAX_PORT}.`);
+  }
+  return port;
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replaceAll("&", "&amp;")
+    .replaceAll("<", "&lt;")
+    .replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;")
+    .replaceAll("'", "&#39;");
+}
+
+function toPosixPath(filePath) {
+  return filePath.split(path.sep).join("/");
+}
+
+function safeRelativePath(fromPath, targetPath) {
+  const relativePath = path.relative(fromPath, targetPath);
+  if (!relativePath || relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+    return null;
+  }
+  return relativePath;
+}
+
+function humanUrlPath(cwdRealPath, fileRealPath) {
+  const relativePath = safeRelativePath(cwdRealPath, fileRealPath);
+  const visiblePath = relativePath || path.basename(fileRealPath);
+  return `/${toPosixPath(visiblePath).split("/").map(encodeURIComponent).join("/")}`;
+}
+
+function tempHtmlPath(cwdRealPath, fileRealPath) {
+  const relativePath = safeRelativePath(cwdRealPath, fileRealPath) || path.basename(fileRealPath);
+  const sanitizedPath = relativePath
+    .split(path.sep)
+    .join(path.sep)
+    .replace(/[<>:"|?*]/g, "_");
+  const uniqueId = crypto.randomBytes(6).toString("hex");
+  return path.join(os.tmpdir(), "mdopen", uniqueId, `${sanitizedPath}.html`);
+}
+
+async function writeUtf8File(targetPath, content) {
+  await fs.writeFile(targetPath, content, "utf8");
+}
+
+module.exports = {
+  ensureFileIsReadableMarkdown,
+  escapeHtml,
+  humanUrlPath,
+  isMarkdownPath,
+  safeRelativePath,
+  tempHtmlPath,
+  toPosixPath,
+  validatePort,
+  writeUtf8File
+};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@ayushshanker/mdo",
+  "version": "0.1.0",
+  "description": "Preview Markdown files and folders in the browser",
+  "bin": {
+    "mdo": "bin/mdo.js"
+  },
+  "type": "commonjs",
+  "files": [
+    "bin",
+    "lib"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node bin/mdo.js",
+    "test": "node --test"
+  },
+  "keywords": [
+    "markdown",
+    "cli",
+    "preview",
+    "browser"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^14.0.1",
+    "github-markdown-css": "^5.8.1",
+    "highlight.js": "^11.11.1",
+    "markdown-it": "^14.1.0",
+    "markdown-it-anchor": "^9.2.0",
+    "markdown-it-task-lists": "^2.1.1",
+    "open": "^10.2.0"
+  }
+}