mdzilla 0.1.0 → 0.2.0

package/README.md

@@ -23,11 +23,11 @@ Works best with [Docus](https://docus.dev)/[Undocs](https://undocs.pages.dev/) d
 ## Quick Start
 
 ```sh
-npx mdzilla <dir>                 # Browse local docs directory
-npx mdzilla <file.md>             # Render a single markdown file
-npx mdzilla gh:owner/repo         # Browse GitHub repo docs
-npx mdzilla npm:package-name      # Browse npm package docs
-npx mdzilla https://example.com   # Browse remote docs via HTTP
+npx mdzilla <source>                     # Open docs in browser
+npx mdzilla <source> <path>              # Render a specific page
+npx mdzilla <source> <query>             # Search docs
+npx mdzilla <file.md>                    # Render a single markdown file
+npx mdzilla <source> --export <outdir>   # Export docs to flat .md files
 ```
 
 ## Agent Skill
@@ -58,18 +58,18 @@ Flatten any docs source into plain `.md` files:
 npx mdzilla <source> --export <outdir>
 ```
 
-### Single Page
+### Smart Resolve
 
-Print a specific page by path and exit:
+The second positional argument is smart-resolved: if it matches a navigation path, the page is rendered; otherwise it's treated as a search query.
 
 ```sh
-npx mdzilla gh:nuxt/nuxt --page /getting-started/seo-meta
-npx mdzilla gh:nuxt/nuxt --plain --page /getting-started/seo-meta
+npx mdzilla gh:unjs/h3 /guide/basics    # Render a specific page
+npx mdzilla gh:unjs/h3 router           # Search for 'router'
 ```
 
-### Headless Mode
+### Plain Mode
 
-Use `--plain` (or `--headless`) for non-interactive output — works like `cat` but for rendered markdown. Auto-enabled when piping output or when called by AI agents.
+Use `--plain` for plain text output. Auto-enabled when piping output or when called by AI agents.
 
 ```sh
 npx mdzilla README.md --plain          # Pretty-print a markdown file
@@ -77,69 +77,56 @@ npx mdzilla README.md | head           # Auto-plain when piped (no TTY)
 npx mdzilla gh:unjs/h3 --plain         # List all pages in plain text
 ```
 
-### Keyboard Controls
-
-<details>
-<summary><strong>Browse mode</strong></summary>
-
-| Key                   | Action               |
-| :-------------------- | :------------------- |
-| `↑` `↓` / `j` `k`     | Navigate entries     |
-| `Enter` / `Tab` / `→` | Focus content        |
-| `Space` / `PgDn`      | Page down            |
-| `b` / `PgUp`          | Page up              |
-| `g` / `G`             | Jump to first / last |
-| `/`                   | Search               |
-| `t`                   | Toggle sidebar       |
-| `q`                   | Quit                 |
+## Programmatic API
 
-</details>
+### Export Docs
 
-<details>
-<summary><strong>Content mode</strong></summary>
-
-| Key                 | Action                |
-| :------------------ | :-------------------- |
-| `↑` `↓` / `j` `k`   | Scroll                |
-| `Space` / `PgDn`    | Page down             |
-| `b` / `PgUp`        | Page up               |
-| `g` / `G`           | Jump to top / bottom  |
-| `/`                 | Search in page        |
-| `n` / `N`           | Next / previous match |
-| `Tab` / `Shift+Tab` | Cycle links           |
-| `Enter`             | Open link             |
-| `Backspace` / `Esc` | Back to nav           |
-| `q`                 | Quit                  |
+One-call export — resolves source, loads, and writes flat `.md` files:
 
-</details>
+```js
+import { exportSource } from "mdzilla";
 
-<details>
-<summary><strong>Search mode</strong></summary>
+await exportSource("./docs", "./dist/docs", {
+  title: "My Docs",
+  filter: (e) => !e.entry.path.startsWith("/blog"),
+});
 
-| Key     | Action           |
-| :------ | :--------------- |
-| _Type_  | Filter results   |
-| `↑` `↓` | Navigate results |
-| `Enter` | Confirm          |
-| `Esc`   | Cancel           |
+// Works with any source
+await exportSource("gh:unjs/h3", "./dist/h3-docs");
+await exportSource("npm:h3", "./dist/h3-docs", { plainText: true });
+await exportSource("https://h3.unjs.io", "./dist/h3-docs");
+```
 
-</details>
+### Collection
 
-## Programmatic API
+`Collection` is the main class for working with documentation programmatically — browse the nav tree, read page content, search, and filter entries.
 
 ```js
-import { DocsManager, DocsSourceFS } from "mdzilla";
+import { Collection, resolveSource } from "mdzilla";
 
-const docs = new DocsManager(new DocsSourceFS("./docs"));
+const docs = new Collection(resolveSource("./docs"));
 await docs.load();
 
-// Browse the navigation tree
-console.log(docs.tree);
+docs.tree; // NavEntry[] — nested navigation tree
+docs.flat; // FlatEntry[] — flattened list with depth info
+docs.pages; // FlatEntry[] — only navigable pages (no directory stubs)
+
+// Read page content
+const page = docs.findByPath("/guide/installation");
+const content = await docs.getContent(page);
 
-// Get page content
-const content = await docs.getContent(docs.flat[0]);
+// Resolve a page flexibly (exact match, prefix stripping, direct fetch)
+const { entry, raw } = await docs.resolvePage("/docs/guide/installation");
+
+// Fuzzy search
+const results = docs.filter("instal"); // sorted by match score
+
+// Substring match (returns indices into docs.flat)
+const indices = docs.matchIndices("getting started");
 ```
 
+`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`).
+
 ## Development
 
 <details>

package/dist/_chunks/exporter.mjs

@@ -1,10 +1,10 @@
+import { parseMeta, renderToMarkdown, renderToText } from "md4x";
 import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, join } from "node:path";
-import { parseMeta, renderToMarkdown, renderToText } from "md4x";
 import { existsSync } from "node:fs";
 import { tmpdir } from "node:os";
-//#region src/docs/manager.ts
-var DocsManager = class {
+//#region src/collection.ts
+var Collection = class {
 	source;
 	tree = [];
 	flat = [];
@@ -36,10 +36,51 @@ var DocsManager = class {
 	invalidate(filePath) {
 		this._contentCache.delete(filePath);
 	}
-	/** Fuzzy filter flat entries by query string. */
+	/** Fuzzy filter flat entries by query string (title and path only). */
 	filter(query) {
 		return fuzzyFilter(this.flat, query, ({ entry }) => [entry.title, entry.path]);
 	}
+	/** Search flat entries by query string, including page contents. Yields scored results as found. */
+	async *search(query) {
+		if (!query) return;
+		const lower = query.toLowerCase();
+		const terms = lower.split(/\s+/).filter(Boolean);
+		const matchAll = (text) => terms.every((t) => text.includes(t));
+		const seen = /* @__PURE__ */ new Set();
+		for (const flat of this.flat) {
+			if (flat.entry.page === false) continue;
+			if (seen.has(flat.entry.path)) continue;
+			seen.add(flat.entry.path);
+			const titleLower = flat.entry.title.toLowerCase();
+			const titleMatch = matchAll(titleLower) || matchAll(flat.entry.path.toLowerCase());
+			const content = await this.getContent(flat);
+			const contentLower = content?.toLowerCase();
+			const contentHit = contentLower ? matchAll(contentLower) : false;
+			if (!titleMatch && !contentHit) continue;
+			let score = 300;
+			let heading;
+			if (titleMatch) score = titleLower === lower ? 0 : 100;
+			else if (content) {
+				const meta = parseMeta(content);
+				for (const h of meta.headings || []) {
+					const hLower = h.text.toLowerCase();
+					if (matchAll(hLower)) {
+						score = hLower === lower ? 150 : 200;
+						heading = h.text;
+						break;
+					}
+				}
+			}
+			const contentMatches = content ? findMatchLines(content, lower) : [];
+			yield {
+				flat,
+				score,
+				titleMatch,
+				heading,
+				contentMatches
+			};
+		}
+	}
 	/** Flat entries that are navigable pages (excludes directory stubs). */
 	get pages() {
 		return this.flat.filter((f) => f.entry.page !== false);
@@ -79,23 +120,18 @@ var DocsManager = class {
 		if (raw) return { raw };
 		return {};
 	}
-	/** Return indices of matching flat entries (case-insensitive substring). */
-	matchIndices(query) {
-		if (!query) return [];
-		const lower = query.toLowerCase();
-		const matched = /* @__PURE__ */ new Set();
-		for (let i = 0; i < this.flat.length; i++) {
-			const { entry } = this.flat[i];
-			if (entry.title.toLowerCase().includes(lower) || entry.path.toLowerCase().includes(lower)) {
-				matched.add(i);
-				const parentDepth = this.flat[i].depth;
-				for (let j = i + 1; j < this.flat.length; j++) {
-					if (this.flat[j].depth <= parentDepth) break;
-					matched.add(j);
-				}
-			}
+	/** Suggest related pages for a query (fuzzy + keyword fallback). */
+	suggest(query, max = 5) {
+		let results = this.filter(query);
+		if (results.length > 0) return results.slice(0, max);
+		const segments = query.replace(/^\/+/, "").split("/").filter(Boolean);
+		const lastSegment = segments.at(-1);
+		if (lastSegment && lastSegment !== query) {
+			results = this.filter(lastSegment);
+			if (results.length > 0) return results.slice(0, max);
 		}
-		return [...matched].sort((a, b) => a - b);
+		const keywords = segments.flatMap((s) => s.split("-")).filter(Boolean);
+		return this.pages.filter((f) => keywords.some((kw) => f.entry.title.toLowerCase().includes(kw) || f.entry.path.toLowerCase().includes(kw))).slice(0, max);
 	}
 };
 function flattenTree(entries, depth, fileMap) {
@@ -144,7 +180,7 @@ function fuzzyFilter(items, query, getText) {
 		let best = Infinity;
 		for (const text of getText(item)) {
 			const s = fuzzyMatch(query, text);
-			if (s >= 0 && s < best) best = s;
+			if (s !== -1 && s < best) best = s;
 		}
 		if (best < Infinity) scored.push({
 			item,
@@ -154,11 +190,52 @@ function fuzzyFilter(items, query, getText) {
 	scored.sort((a, b) => a.score - b.score);
 	return scored.map((s) => s.item);
 }
+function findMatchLines(content, lowerQuery, contextLines = 1) {
+	const matches = [];
+	const lines = content.split("\n");
+	for (let i = 0; i < lines.length; i++) if (lines[i].toLowerCase().includes(lowerQuery)) {
+		const context = [];
+		for (let j = Math.max(0, i - contextLines); j <= Math.min(lines.length - 1, i + contextLines); j++) if (j !== i) context.push(lines[j].trim());
+		matches.push({
+			line: i + 1,
+			text: lines[i].trim(),
+			context
+		});
+	}
+	return matches;
+}
 //#endregion
-//#region src/docs/sources/_base.ts
-var DocsSource = class {};
+//#region src/utils.ts
+/** Extract short text snippets around matching terms. */
+function extractSnippets(content, terms, opts = {}) {
+	const { maxSnippets = 3, radius = 80 } = opts;
+	const lower = content.toLowerCase();
+	const positions = [];
+	for (const term of terms) {
+		let idx = lower.indexOf(term);
+		while (idx !== -1 && positions.length < maxSnippets * 2) {
+			positions.push(idx);
+			idx = lower.indexOf(term, idx + term.length);
+		}
+	}
+	positions.sort((a, b) => a - b);
+	const snippets = [];
+	let prevEnd = -1;
+	for (const pos of positions) {
+		if (snippets.length >= maxSnippets) break;
+		const start = Math.max(0, pos - radius);
+		const end = Math.min(content.length, pos + radius);
+		if (start <= prevEnd) continue;
+		prevEnd = end;
+		let snippet = content.slice(start, end).trim().replaceAll(/\s+/g, " ");
+		if (start > 0) snippet = "…" + snippet;
+		if (end < content.length) snippet = snippet + "…";
+		snippets.push(snippet);
+	}
+	return snippets;
+}
 //#endregion
-//#region src/docs/nav.ts
+//#region src/nav.ts
 /**
 * Parse a numbered filename/dirname like "1.guide" or "3.middleware.md"
 * into { order, slug }. Also strips `.draft` suffix.
@@ -301,8 +378,11 @@ async function _scanNav(dirPath, parentPath, options) {
 	return entries;
 }
 //#endregion
-//#region src/docs/sources/fs.ts
-var DocsSourceFS = class extends DocsSource {
+//#region src/sources/_base.ts
+var Source = class {};
+//#endregion
+//#region src/sources/fs.ts
+var FSSource = class extends Source {
 	dir;
 	constructor(dir) {
 		super();
@@ -369,8 +449,8 @@ function reorderTree(entries, manifest) {
 	}
 }
 //#endregion
-//#region src/docs/sources/git.ts
-var DocsSourceGit = class extends DocsSource {
+//#region src/sources/git.ts
+var GitSource = class extends Source {
 	src;
 	options;
 	_fs;
@@ -398,16 +478,16 @@ var DocsSourceGit = class extends DocsSource {
 				break;
 			}
 		}
-		this._fs = new DocsSourceFS(docsDir);
+		this._fs = new FSSource(docsDir);
 		return this._fs.load();
 	}
 	async readContent(filePath) {
-		if (!this._fs) throw new Error("DocsSourceGit: call load() before readContent()");
+		if (!this._fs) throw new Error("GitSource: call load() before readContent()");
 		return this._fs.readContent(filePath);
 	}
 };
 //#endregion
-//#region src/docs/sources/_npm.ts
+//#region src/sources/_npm.ts
 /**
 * Parse an npm package spec: `[@scope/]name[@version][/subdir]`
 */
@@ -465,8 +545,8 @@ function parseNpmURL(url) {
 	if (shortMatch && !/^(package|settings|signup|login|org|search)$/.test(shortMatch[1])) return shortMatch[1];
 }
 //#endregion
-//#region src/docs/sources/http.ts
-var DocsSourceHTTP = class extends DocsSource {
+//#region src/sources/http.ts
+var HTTPSource = class extends Source {
 	url;
 	options;
 	_contentCache = /* @__PURE__ */ new Map();
@@ -727,8 +807,8 @@ function _resolveHref(href, baseURL) {
 	}
 }
 //#endregion
-//#region src/docs/sources/npm.ts
-var DocsSourceNpm = class extends DocsSource {
+//#region src/sources/npm.ts
+var NpmSource = class extends Source {
 	src;
 	options;
 	_fs;
@@ -758,11 +838,11 @@ var DocsSourceNpm = class extends DocsSource {
 				break;
 			}
 		}
-		this._fs = new DocsSourceFS(docsDir);
+		this._fs = new FSSource(docsDir);
 		return this._fs.load();
 	}
 	async readContent(filePath) {
-		if (!this._fs) throw new Error("DocsSourceNpm: call load() before readContent()");
+		if (!this._fs) throw new Error("NpmSource: call load() before readContent()");
 		return this._fs.readContent(filePath);
 	}
 };
@@ -777,31 +857,65 @@ async function npmProvider(input) {
 	};
 }
 //#endregion
-//#region src/docs/exporter.ts
+//#region src/source.ts
+/**
+* Resolve a source string to the appropriate Source instance.
+*
+* Supports: local paths, `gh:owner/repo`, `npm:package`, `http(s)://...`
+*/
+function resolveSource(input) {
+	if (input.startsWith("http://") || input.startsWith("https://")) return new HTTPSource(input);
+	if (input.startsWith("gh:")) return new GitSource(input);
+	if (input.startsWith("npm:")) return new NpmSource(input);
+	return new FSSource(input);
+}
+//#endregion
+//#region src/exporter.ts
+/**
+* High-level export: resolve source, load, and export in one call.
+*
+* ```ts
+* await exportSource("./docs", "./dist/docs");
+* await exportSource("gh:unjs/h3", "./dist/h3-docs");
+* await exportSource("npm:h3", "./dist/h3-docs", { plainText: true });
+* await exportSource("https://h3.unjs.io", "./dist/h3-docs");
+* ```
+*/
+async function exportSource(input, dir, options = {}) {
+	const collection = new Collection(typeof input === "string" ? resolveSource(input) : input);
+	await collection.load();
+	await mkdir(dir, { recursive: true });
+	await writeCollection(collection, dir, options);
+	return collection;
+}
 /** Paths to skip during export (generated by source, not actual docs) */
 const IGNORED_PATHS = new Set(["/llms.txt", "/llms-full.txt"]);
 /**
 * Export documentation entries to a local filesystem directory as flat `.md` files.
 *
-* Each entry is written to `<dir>/<path>.md` (or `<dir>/<path>/index.md` for directory
-* index pages). Navigation order is preserved via `order` frontmatter in pages and
-* `.navigation.yml` files in directories.
+* Each entry is written to `<dir>/<prefix>.<slug>.md` (or `<dir>/<prefix>.<slug>/index.md`
+* for directory index pages). Navigation order is preserved via numeric prefixes on
+* directories and files (e.g., `1.guide/`, `2.getting-started.md`) so the nav scanner
+* can infer order without additional metadata files.
 *
 * A `README.md` table of contents is generated at the root of the output directory.
 */
-async function exportDocsToFS(manager, dir, options = {}) {
-	const rootEntry = manager.flat.find((f) => f.entry.path === "/");
+async function writeCollection(collection, dir, options = {}) {
+	const rootEntry = collection.flat.find((f) => f.entry.path === "/");
 	const tocLines = [`# ${options.title ?? rootEntry?.entry.title ?? "Table of Contents"}`, ""];
 	const writtenFiles = /* @__PURE__ */ new Set();
+	const pathMap = /* @__PURE__ */ new Map();
+	buildNumberedPaths(collection.tree, "", pathMap);
 	const dirPaths = /* @__PURE__ */ new Set();
-	collectDirPaths(manager.tree, dirPaths);
-	for (const flat of manager.flat) {
+	collectDirPaths(collection.tree, dirPaths);
+	for (const flat of collection.flat) {
 		if (options.filter ? !options.filter(flat) : flat.entry.page === false) continue;
 		if (IGNORED_PATHS.has(flat.entry.path)) continue;
-		let content = await manager.getContent(flat);
+		let content = await collection.getContent(flat);
 		if (content === void 0) continue;
 		const cleanContent = options.plainText ? renderToText(content) : renderToMarkdown(content);
-		const filePath = flat.entry.path === "/" || dirPaths.has(flat.entry.path) ? flat.entry.path === "/" ? "/index.md" : `${flat.entry.path}/index.md` : flat.entry.path.endsWith(".md") ? flat.entry.path : `${flat.entry.path}.md`;
+		const numberedPath = pathMap.get(flat.entry.path) ?? flat.entry.path;
+		const filePath = flat.entry.path === "/" || dirPaths.has(flat.entry.path) ? flat.entry.path === "/" ? "/index.md" : `${numberedPath}/index.md` : numberedPath.endsWith(".md") ? numberedPath : `${numberedPath}.md`;
 		const dest = join(dir, filePath);
 		await mkdir(dirname(dest), { recursive: true });
 		await writeFile(dest, cleanContent, "utf8");
@@ -813,7 +927,6 @@ async function exportDocsToFS(manager, dir, options = {}) {
 	let tocFile = options.tocFile ?? "README.md";
 	if (writtenFiles.has(tocFile)) tocFile = `_${tocFile}`;
 	await writeFile(join(dir, tocFile), tocLines.join("\n") + "\n", "utf8");
-	await writeFile(join(dir, "_navigation.json"), JSON.stringify(manager.tree, null, 2) + "\n", "utf8");
 }
 /** Collect all paths that are directories (have children in the tree). */
 function collectDirPaths(entries, set) {
@@ -822,5 +935,16 @@ function collectDirPaths(entries, set) {
 		collectDirPaths(entry.children, set);
 	}
 }
+/**
+* Build a map from nav path → numbered filesystem path.
+* Uses sibling index as the numeric prefix (e.g., `/guide` → `/1.guide`).
+*/
+function buildNumberedPaths(entries, parentPath, map) {
+	for (const [i, entry] of entries.entries()) {
+		const numbered = `${parentPath}/${i}.${entry.slug || "index"}`;
+		map.set(entry.path, numbered);
+		if (entry.children?.length) buildNumberedPaths(entry.children, numbered, map);
+	}
+}
 //#endregion
-export { DocsSourceFS as a, DocsSourceGit as i, DocsSourceNpm as n, DocsSource as o, DocsSourceHTTP as r, DocsManager as s, exportDocsToFS as t };
+export { HTTPSource as a, Source as c, NpmSource as i, extractSnippets as l, writeCollection as n, GitSource as o, resolveSource as r, FSSource as s, exportSource as t, Collection as u };