@mzebley/mark-down-cli 1.0.0 → 1.2.0

package/README.md

@@ -32,10 +32,10 @@ npx @mzebley/mark-down-cli build content/snippets
 ## Usage
 
 ```bash
-mark-down build <sourceDir> [options]
+mark-down <command> [options]
 ```
 
-The CLI walks the directory tree, gathers front matter, and writes `snippets-index.json` alongside your Markdown files by default.
+The CLI walks the directory tree, gathers front matter, and writes `snippets-index.json` alongside your Markdown files by default. It can also pre-render HTML files that already contain `data-snippet` placeholders.
 
 ## Commands
 
@@ -53,12 +53,27 @@ The CLI walks the directory tree, gathers front matter, and writes `snippets-ind
 - Logs progress with the familiar `[mark↓]` prefix.
 - Accepts the same options as `build`.
 
+### `mark-down compile-page <inputHtml>`
+
+- Reads an HTML file that contains elements with `data-snippet` attributes.
+- Resolves snippet metadata from `snippets-index.json` (auto-detected next to the HTML file or provided via `--manifest`).
+- Loads Markdown from disk, strips front matter, and renders HTML with the same `marked` pipeline as the runtime.
+- Injects the rendered HTML as the element `innerHTML` and writes the result to `dist/<file>.html` by default.
+- Use `--outDir` to change the output directory or `--inPlace` to overwrite the source file.
+- Unknown slugs are left untouched and logged as warnings. Table-of-contents generation remains a runtime concern.
+
 ## Configuration options
 
 The CLI stays intentionally small so it can be composed inside any toolchain. Currently supported flags:
 
 - `-o, --output <path>` – write the manifest to a custom file instead of `<sourceDir>/snippets-index.json`.
 
+### `compile-page` options
+
+- `--manifest <path>` – path to `snippets-index.json`. Defaults to the file next to `<inputHtml>`.
+- `--outDir <dir>` – output directory for compiled HTML. Defaults to `dist`.
+- `--inPlace` – overwrite the input HTML file instead of writing to `dist/`.
+
 Add flags directly after the command (`mark-down build content/snippets -o public/snippets-index.json`). Package scripts can capture these options as well.
 
 ## Watching for changes

package/dist/index.cjs

@@ -231,9 +231,100 @@ function debounce(fn, delay) {
   };
 }
 
+// src/compile-page.ts
+var import_promises2 = __toESM(require("fs/promises"), 1);
+var import_node_path3 = __toESM(require("path"), 1);
+var import_cheerio = require("cheerio");
+var import_mark_down2 = require("@mzebley/mark-down");
+var DEFAULT_OUT_DIR = "dist";
+async function compilePage(inputHtml, options = {}) {
+  const sourcePath = import_node_path3.default.resolve(inputHtml);
+  await assertExists(sourcePath, `Input HTML file not found at '${inputHtml}'.`);
+  const manifestPath = await resolveManifestPath(sourcePath, options.manifest);
+  const manifestDir = import_node_path3.default.dirname(manifestPath);
+  const manifest = await loadManifest(manifestPath);
+  const rawHtml = await import_promises2.default.readFile(sourcePath, "utf8");
+  const doctypeMatch = rawHtml.match(/^(<!doctype[^>]*>\s*)/i);
+  const doctype = doctypeMatch?.[1] ?? "";
+  const dom = (0, import_cheerio.load)(rawHtml, { decodeEntities: false });
+  const targets = dom("[data-snippet]").toArray();
+  for (const node of targets) {
+    const element = dom(node);
+    const slug = element.attr("data-snippet");
+    if (!slug) {
+      continue;
+    }
+    const entry = manifest.find((item) => item.slug === slug);
+    if (!entry) {
+      console.warn(`mark\u2193: no snippet found for "${slug}"`);
+      continue;
+    }
+    const snippetPath = import_node_path3.default.resolve(manifestDir, entry.path);
+    let raw;
+    try {
+      raw = await import_promises2.default.readFile(snippetPath, "utf8");
+    } catch (error) {
+      console.warn(`mark\u2193: failed to read snippet at '${entry.path}'`, error);
+      continue;
+    }
+    let body = raw;
+    let frontMatterSlug;
+    try {
+      const frontMatter = (0, import_mark_down2.parseFrontMatter)(raw);
+      body = frontMatter.content;
+      frontMatterSlug = frontMatter.slug;
+    } catch (error) {
+      console.warn(`mark\u2193: failed to parse front matter for '${entry.path}'`, error);
+    }
+    const html = (0, import_mark_down2.renderMarkdown)(body);
+    element.html(html);
+    if (!element.attr("id")) {
+      element.attr("id", frontMatterSlug ?? `snippet-${slug}`);
+    }
+  }
+  const outputDir = options.inPlace ? import_node_path3.default.dirname(sourcePath) : import_node_path3.default.resolve(options.outDir ?? DEFAULT_OUT_DIR);
+  if (!options.inPlace) {
+    await import_promises2.default.mkdir(outputDir, { recursive: true });
+  }
+  const outputPath = options.inPlace ? sourcePath : import_node_path3.default.join(outputDir, import_node_path3.default.basename(sourcePath));
+  const outputHtml = `${doctype}${dom.html() ?? ""}`;
+  await import_promises2.default.writeFile(outputPath, outputHtml);
+  logEvent("info", "compile_page.written", { outputPath });
+  return outputPath;
+}
+async function resolveManifestPath(inputHtml, manifestFlag) {
+  const manifestPath = manifestFlag ? import_node_path3.default.resolve(manifestFlag) : import_node_path3.default.join(import_node_path3.default.dirname(import_node_path3.default.resolve(inputHtml)), "snippets-index.json");
+  await assertExists(manifestPath, `Manifest file not found at '${manifestPath}'.`);
+  return manifestPath;
+}
+async function loadManifest(manifestPath) {
+  let raw;
+  try {
+    raw = await import_promises2.default.readFile(manifestPath, "utf8");
+  } catch (error) {
+    throw new Error(`Failed to read manifest at '${manifestPath}': ${String(error)}`);
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+      throw new Error("Manifest must be a JSON array.");
+    }
+    return parsed;
+  } catch (error) {
+    throw new Error(`Failed to parse manifest at '${manifestPath}': ${String(error)}`);
+  }
+}
+async function assertExists(target, message) {
+  try {
+    await import_promises2.default.access(target);
+  } catch {
+    throw new Error(message);
+  }
+}
+
 // src/index.ts
 var program = new import_commander.Command();
-program.name("mark-down").description(`${brand} CLI for building snippet manifests`).version("0.1.0");
+program.name("mark-down").description(`${brand} CLI for building snippet manifests`).version("1.2.0");
 program.command("build").argument("[sourceDir]", "directory containing snippets", "content/snippets").option("-o, --output <path>", "where to write snippets-index.json").action(async (sourceDir, options) => {
   try {
     const result = await buildManifestFile({ sourceDir, outputPath: options.output });
@@ -252,6 +343,17 @@ program.command("watch").argument("[sourceDir]", "directory containing snippets"
     handleError(error);
   }
 });
+program.command("compile-page").argument("<inputHtml>", "HTML file containing data-snippet placeholders").option("--manifest <path>", "path to snippets-index.json").option("--outDir <path>", "output directory for compiled HTML", "dist").option("--inPlace", "overwrite the input HTML file instead of writing to outDir").action(async (inputHtml, options) => {
+  try {
+    await compilePage(inputHtml, {
+      manifest: options.manifest,
+      outDir: options.outDir,
+      inPlace: options.inPlace
+    });
+  } catch (error) {
+    handleError(error);
+  }
+});
 program.parseAsync(process.argv).catch(handleError);
 function handleError(error) {
   const err = error;

package/dist/index.js

@@ -208,9 +208,100 @@ function debounce(fn, delay) {
   };
 }
 
+// src/compile-page.ts
+import fs2 from "fs/promises";
+import path3 from "path";
+import { load as loadHtml } from "cheerio";
+import { parseFrontMatter, renderMarkdown } from "@mzebley/mark-down";
+var DEFAULT_OUT_DIR = "dist";
+async function compilePage(inputHtml, options = {}) {
+  const sourcePath = path3.resolve(inputHtml);
+  await assertExists(sourcePath, `Input HTML file not found at '${inputHtml}'.`);
+  const manifestPath = await resolveManifestPath(sourcePath, options.manifest);
+  const manifestDir = path3.dirname(manifestPath);
+  const manifest = await loadManifest(manifestPath);
+  const rawHtml = await fs2.readFile(sourcePath, "utf8");
+  const doctypeMatch = rawHtml.match(/^(<!doctype[^>]*>\s*)/i);
+  const doctype = doctypeMatch?.[1] ?? "";
+  const dom = loadHtml(rawHtml, { decodeEntities: false });
+  const targets = dom("[data-snippet]").toArray();
+  for (const node of targets) {
+    const element = dom(node);
+    const slug = element.attr("data-snippet");
+    if (!slug) {
+      continue;
+    }
+    const entry = manifest.find((item) => item.slug === slug);
+    if (!entry) {
+      console.warn(`mark\u2193: no snippet found for "${slug}"`);
+      continue;
+    }
+    const snippetPath = path3.resolve(manifestDir, entry.path);
+    let raw;
+    try {
+      raw = await fs2.readFile(snippetPath, "utf8");
+    } catch (error) {
+      console.warn(`mark\u2193: failed to read snippet at '${entry.path}'`, error);
+      continue;
+    }
+    let body = raw;
+    let frontMatterSlug;
+    try {
+      const frontMatter = parseFrontMatter(raw);
+      body = frontMatter.content;
+      frontMatterSlug = frontMatter.slug;
+    } catch (error) {
+      console.warn(`mark\u2193: failed to parse front matter for '${entry.path}'`, error);
+    }
+    const html = renderMarkdown(body);
+    element.html(html);
+    if (!element.attr("id")) {
+      element.attr("id", frontMatterSlug ?? `snippet-${slug}`);
+    }
+  }
+  const outputDir = options.inPlace ? path3.dirname(sourcePath) : path3.resolve(options.outDir ?? DEFAULT_OUT_DIR);
+  if (!options.inPlace) {
+    await fs2.mkdir(outputDir, { recursive: true });
+  }
+  const outputPath = options.inPlace ? sourcePath : path3.join(outputDir, path3.basename(sourcePath));
+  const outputHtml = `${doctype}${dom.html() ?? ""}`;
+  await fs2.writeFile(outputPath, outputHtml);
+  logEvent("info", "compile_page.written", { outputPath });
+  return outputPath;
+}
+async function resolveManifestPath(inputHtml, manifestFlag) {
+  const manifestPath = manifestFlag ? path3.resolve(manifestFlag) : path3.join(path3.dirname(path3.resolve(inputHtml)), "snippets-index.json");
+  await assertExists(manifestPath, `Manifest file not found at '${manifestPath}'.`);
+  return manifestPath;
+}
+async function loadManifest(manifestPath) {
+  let raw;
+  try {
+    raw = await fs2.readFile(manifestPath, "utf8");
+  } catch (error) {
+    throw new Error(`Failed to read manifest at '${manifestPath}': ${String(error)}`);
+  }
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+      throw new Error("Manifest must be a JSON array.");
+    }
+    return parsed;
+  } catch (error) {
+    throw new Error(`Failed to parse manifest at '${manifestPath}': ${String(error)}`);
+  }
+}
+async function assertExists(target, message) {
+  try {
+    await fs2.access(target);
+  } catch {
+    throw new Error(message);
+  }
+}
+
 // src/index.ts
 var program = new Command();
-program.name("mark-down").description(`${brand} CLI for building snippet manifests`).version("0.1.0");
+program.name("mark-down").description(`${brand} CLI for building snippet manifests`).version("1.2.0");
 program.command("build").argument("[sourceDir]", "directory containing snippets", "content/snippets").option("-o, --output <path>", "where to write snippets-index.json").action(async (sourceDir, options) => {
   try {
     const result = await buildManifestFile({ sourceDir, outputPath: options.output });
@@ -229,6 +320,17 @@ program.command("watch").argument("[sourceDir]", "directory containing snippets"
     handleError(error);
   }
 });
+program.command("compile-page").argument("<inputHtml>", "HTML file containing data-snippet placeholders").option("--manifest <path>", "path to snippets-index.json").option("--outDir <path>", "output directory for compiled HTML", "dist").option("--inPlace", "overwrite the input HTML file instead of writing to outDir").action(async (inputHtml, options) => {
+  try {
+    await compilePage(inputHtml, {
+      manifest: options.manifest,
+      outDir: options.outDir,
+      inPlace: options.inPlace
+    });
+  } catch (error) {
+    handleError(error);
+  }
+});
 program.parseAsync(process.argv).catch(handleError);
 function handleError(error) {
   const err = error;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mzebley/mark-down-cli",
-  "version": "1.0.0",
+  "version": "1.2.0",
   "description": "mark↓ CLI for building snippet manifests",
   "type": "module",
   "bin": {
@@ -18,6 +18,7 @@
   },
   "dependencies": {
     "@mzebley/mark-down": "file:../core",
+    "cheerio": "^1.0.0",
     "chokidar": "^3.6.0",
     "commander": "^11.1.0",
     "fast-glob": "^3.3.2",

package/src/compile-page.ts

@@ -0,0 +1,116 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { load as loadHtml } from "cheerio";
+import { parseFrontMatter, renderMarkdown, type SnippetMeta } from "@mzebley/mark-down";
+import { logEvent } from "./logger.js";
+
+export interface CompilePageOptions {
+  manifest?: string;
+  outDir?: string;
+  inPlace?: boolean;
+}
+
+const DEFAULT_OUT_DIR = "dist";
+
+export async function compilePage(inputHtml: string, options: CompilePageOptions = {}): Promise<string> {
+  const sourcePath = path.resolve(inputHtml);
+  await assertExists(sourcePath, `Input HTML file not found at '${inputHtml}'.`);
+
+  const manifestPath = await resolveManifestPath(sourcePath, options.manifest);
+  const manifestDir = path.dirname(manifestPath);
+  const manifest = await loadManifest(manifestPath);
+
+  const rawHtml = await fs.readFile(sourcePath, "utf8");
+  const doctypeMatch = rawHtml.match(/^(<!doctype[^>]*>\s*)/i);
+  const doctype = doctypeMatch?.[1] ?? "";
+  const dom = loadHtml(rawHtml, { decodeEntities: false });
+
+  const targets = dom("[data-snippet]").toArray();
+  for (const node of targets) {
+    const element = dom(node);
+    const slug = element.attr("data-snippet");
+    if (!slug) {
+      continue;
+    }
+    const entry = manifest.find((item) => item.slug === slug);
+    if (!entry) {
+      console.warn(`mark↓: no snippet found for "${slug}"`);
+      continue;
+    }
+
+    const snippetPath = path.resolve(manifestDir, entry.path);
+    let raw: string;
+    try {
+      raw = await fs.readFile(snippetPath, "utf8");
+    } catch (error) {
+      console.warn(`mark↓: failed to read snippet at '${entry.path}'`, error);
+      continue;
+    }
+
+    let body = raw;
+    let frontMatterSlug: string | undefined;
+    try {
+      const frontMatter = parseFrontMatter(raw);
+      body = frontMatter.content;
+      frontMatterSlug = frontMatter.slug;
+    } catch (error) {
+      console.warn(`mark↓: failed to parse front matter for '${entry.path}'`, error);
+    }
+
+    const html = renderMarkdown(body);
+    element.html(html);
+
+    if (!element.attr("id")) {
+      element.attr("id", frontMatterSlug ?? `snippet-${slug}`);
+    }
+  }
+
+  const outputDir = options.inPlace ? path.dirname(sourcePath) : path.resolve(options.outDir ?? DEFAULT_OUT_DIR);
+  if (!options.inPlace) {
+    await fs.mkdir(outputDir, { recursive: true });
+  }
+  const outputPath = options.inPlace
+    ? sourcePath
+    : path.join(outputDir, path.basename(sourcePath));
+
+  const outputHtml = `${doctype}${dom.html() ?? ""}`;
+  await fs.writeFile(outputPath, outputHtml);
+
+  logEvent("info", "compile_page.written", { outputPath });
+  return outputPath;
+}
+
+async function resolveManifestPath(inputHtml: string, manifestFlag?: string): Promise<string> {
+  const manifestPath = manifestFlag
+    ? path.resolve(manifestFlag)
+    : path.join(path.dirname(path.resolve(inputHtml)), "snippets-index.json");
+  await assertExists(manifestPath, `Manifest file not found at '${manifestPath}'.`);
+  return manifestPath;
+}
+
+async function loadManifest(manifestPath: string): Promise<SnippetMeta[]> {
+  let raw: string;
+  try {
+    raw = await fs.readFile(manifestPath, "utf8");
+  } catch (error) {
+    throw new Error(`Failed to read manifest at '${manifestPath}': ${String(error)}`);
+  }
+
+  try {
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) {
+      throw new Error("Manifest must be a JSON array.");
+    }
+    return parsed as SnippetMeta[];
+  } catch (error) {
+    throw new Error(`Failed to parse manifest at '${manifestPath}': ${String(error)}`);
+  }
+}
+
+async function assertExists(target: string, message: string) {
+  try {
+    await fs.access(target);
+  } catch {
+    throw new Error(message);
+  }
+}

package/src/index.ts

@@ -4,12 +4,13 @@ import { buildManifestFile } from "./manifest.js";
 import { watch as watchSnippets } from "./watch.js";
 import { brand, logEvent } from "./logger.js";
 import { DuplicateSlugError } from "./errors.js";
+import { compilePage } from "./compile-page.js";
 
 const program = new Command();
 program
   .name("mark-down")
   .description(`${brand} CLI for building snippet manifests`)
-  .version("0.1.0");
+  .version("1.2.0");
 
 program
   .command("build")
@@ -39,6 +40,24 @@ program
     }
   });
 
+program
+  .command("compile-page")
+  .argument("<inputHtml>", "HTML file containing data-snippet placeholders")
+  .option("--manifest <path>", "path to snippets-index.json")
+  .option("--outDir <path>", "output directory for compiled HTML", "dist")
+  .option("--inPlace", "overwrite the input HTML file instead of writing to outDir")
+  .action(async (inputHtml: string, options: { manifest?: string; outDir?: string; inPlace?: boolean }) => {
+    try {
+      await compilePage(inputHtml, {
+        manifest: options.manifest,
+        outDir: options.outDir,
+        inPlace: options.inPlace
+      });
+    } catch (error) {
+      handleError(error);
+    }
+  });
+
 program.parseAsync(process.argv).catch(handleError);
 
 function handleError(error: unknown) {