mdzilla 0.2.0 → 0.2.1

package/README.md

@@ -67,6 +67,19 @@ npx mdzilla gh:unjs/h3 /guide/basics    # Render a specific page
 npx mdzilla gh:unjs/h3 router           # Search for 'router'
 ```
 
+### Web Server
+
+Running `mdzilla <source>` without a query opens docs in the browser with a local web server:
+
+```sh
+npx mdzilla ./docs                   # Browse local docs in browser
+npx mdzilla gh:unjs/h3               # Browse GitHub repo docs
+```
+
+The web UI provides a sidebar navigation, full-text search, syntax-highlighted pages, and dark/light theme support.
+
+For local sources (`FSSource`), the server watches for file changes and live-reloads both the navigation and the current page via Server-Sent Events — no manual refresh needed.
+
 ### Plain Mode
 
 Use `--plain` for plain text output. Auto-enabled when piping output or when called by AI agents.
@@ -123,6 +136,13 @@ const results = docs.filter("instal"); // sorted by match score
 
 // Substring match (returns indices into docs.flat)
 const indices = docs.matchIndices("getting started");
+
+// Watch for changes (FSSource only) with live reload
+docs.watch();
+const unsub = docs.onChange((path) => {
+  console.log(`Changed: ${path}`);
+});
+// Later: unsub() and docs.unwatch()
 ```
 
 `resolveSource` auto-detects the source type from the input string (`gh:`, `npm:`, `https://`, or local path). You can also use specific source classes directly (`FSSource`, `GitSource`, `NpmSource`, `HTTPSource`).

package/dist/_chunks/exporter.mjs

@@ -1,7 +1,7 @@
 import { parseMeta, renderToMarkdown, renderToText } from "md4x";
 import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { existsSync, watch } from "node:fs";
 import { basename, dirname, extname, join } from "node:path";
-import { existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 //#region src/collection.ts
 var Collection = class {
@@ -10,6 +10,8 @@ var Collection = class {
 	flat = [];
 	_fileMap = /* @__PURE__ */ new Map();
 	_contentCache = /* @__PURE__ */ new Map();
+	_changeListeners = /* @__PURE__ */ new Set();
+	_reloadTimer;
 	constructor(source) {
 		this.source = source;
 	}
@@ -23,6 +25,28 @@ var Collection = class {
 	async reload() {
 		return this.load();
 	}
+	/** Start watching source for changes. Debounces, reloads collection, and notifies listeners. */
+	watch() {
+		this.source.watch(({ path }) => {
+			clearTimeout(this._reloadTimer);
+			this._reloadTimer = setTimeout(() => {
+				this.reload().then(() => {
+					for (const listener of this._changeListeners) listener(path);
+				});
+			}, 100);
+		});
+	}
+	/** Stop watching source. */
+	unwatch() {
+		clearTimeout(this._reloadTimer);
+		this.source.unwatch();
+		this._changeListeners.clear();
+	}
+	/** Register a change listener. Returns unsubscribe function. */
+	onChange(listener) {
+		this._changeListeners.add(listener);
+		return () => this._changeListeners.delete(listener);
+	}
 	/** Get raw file content for a flat entry (cached). */
 	async getContent(entry) {
 		if (!entry.filePath || entry.entry.page === false) return void 0;
@@ -354,11 +378,13 @@ async function _scanNav(dirPath, parentPath, options) {
 		} else if (extname(entry) === ".md") {
 			const { order, slug, draft } = parseNumberedName(basename(entry));
 			if (draft && !options.drafts) continue;
-			const meta = applyNavigationOverride(parseMeta(await readFile(fullPath, "utf8")));
+			const rawMeta = parseMeta(await readFile(fullPath, "utf8"));
+			const meta = applyNavigationOverride(rawMeta);
 			if (meta.navigation === false) continue;
 			const resolvedOrder = typeof meta.order === "number" ? meta.order : order;
 			const resolvedSlug = slug === "index" ? "" : slug;
-			const title = meta.title || humanizeSlug(slug) || "index";
+			const firstHeading = rawMeta.headings?.find((h) => h.level === 1)?.text;
+			const title = meta.title || firstHeading || humanizeSlug(slug) || "index";
 			const entryPath = resolvedSlug === "" ? parentPath === "/" ? "/" : parentPath : parentPath === "/" ? `/${resolvedSlug}` : `${parentPath}/${resolvedSlug}`;
 			const extra = extraMeta(meta);
 			const navEntry = {
@@ -366,6 +392,7 @@ async function _scanNav(dirPath, parentPath, options) {
 				path: entryPath,
 				title,
 				order: resolvedOrder,
+				...firstHeading && firstHeading !== title ? { heading: firstHeading } : {},
 				...meta.icon ? { icon: meta.icon } : {},
 				...meta.description ? { description: meta.description } : {},
 				...draft ? { draft: true } : {},
@@ -379,11 +406,17 @@ async function _scanNav(dirPath, parentPath, options) {
 }
 //#endregion
 //#region src/sources/_base.ts
-var Source = class {};
+var Source = class {
+	/** Start watching for file changes. Override in sources that support it. */
+	watch(_callback) {}
+	/** Stop watching. Override in sources that support it. */
+	unwatch() {}
+};
 //#endregion
 //#region src/sources/fs.ts
 var FSSource = class extends Source {
 	dir;
+	_watcher;
 	constructor(dir) {
 		super();
 		this.dir = dir;
@@ -399,6 +432,17 @@ var FSSource = class extends Source {
 	async readContent(filePath) {
 		return readFile(filePath, "utf8");
 	}
+	watch(callback) {
+		this.unwatch();
+		this._watcher = watch(this.dir, { recursive: true }, (_event, filename) => {
+			if (!filename || filename.startsWith(".") || filename.startsWith("_")) return;
+			callback({ path: "/" + filename });
+		});
+	}
+	unwatch() {
+		this._watcher?.close();
+		this._watcher = void 0;
+	}
 };
 function parseSlug(name) {
 	const base = name.endsWith(".draft") ? name.slice(0, -6) : name;