mdzilla 0.0.3 → 0.0.5

package/README.md

@@ -12,7 +12,9 @@ Markdown browser for humans and agents.
 
 </p>
 
-> Browse docs from local directories, GitHub repos, and remote websites — all from your terminal. Built on [md4x](https://github.com/unjs/md4x), [mdream](https://github.com/harlan-zw/mdream), [giget](https://github.com/unjs/giget) and [speed-highlight](https://github.com/speed-highlight/core).
+> Browse docs from local directories, GitHub repos, and remote websites — all from your terminal.
+
+Built with [md4x](https://github.com/unjs/md4x), [mdream](https://github.com/harlan-zw/mdream), [giget](https://github.com/unjs/giget) and [speed-highlight](https://github.com/speed-highlight/core), [nitro](https://v3.nitro.build/), [h3](https://h3.dev/), [srvx](https://srvx.h3.dev/) and [vite](https://vite.dev/).
 
 Supports any website with [`/llms.txt`](https://llmstxt.org/) or markdown content negotiation.
 

package/dist/_chunks/exporter.mjs

@@ -279,6 +279,7 @@ async function _scanNav(dirPath, parentPath, options) {
 			if (draft && !options.drafts) continue;
 			const meta = applyNavigationOverride(parseMeta(await readFile(fullPath, "utf8")));
 			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 entryPath = resolvedSlug === "" ? parentPath === "/" ? "/" : parentPath : parentPath === "/" ? `/${resolvedSlug}` : `${parentPath}/${resolvedSlug}`;
@@ -287,7 +288,7 @@ async function _scanNav(dirPath, parentPath, options) {
 				slug: resolvedSlug,
 				path: entryPath,
 				title,
-				order,
+				order: resolvedOrder,
 				...meta.icon ? { icon: meta.icon } : {},
 				...meta.description ? { description: meta.description } : {},
 				...draft ? { draft: true } : {},
@@ -308,8 +309,10 @@ var DocsSourceFS = class extends DocsSource {
 		this.dir = dir;
 	}
 	async load() {
+		const tree = await scanNav(this.dir);
+		await applyNavManifest(tree, this.dir);
 		return {
-			tree: await scanNav(this.dir),
+			tree,
 			fileMap: await buildFileMap("/", this.dir)
 		};
 	}
@@ -341,6 +344,30 @@ async function buildFileMap(parentPath, dirPath) {
 	}
 	return map;
 }
+/**
+* Read `_navigation.json` manifest (exported by mdzilla) and apply its
+* ordering to the scanned nav tree. Only reorders; does not add/remove entries.
+*/
+async function applyNavManifest(tree, dir) {
+	let manifest;
+	try {
+		manifest = JSON.parse(await readFile(join(dir, "_navigation.json"), "utf8"));
+	} catch {
+		return;
+	}
+	reorderTree(tree, manifest);
+}
+/** Recursively reorder tree entries to match manifest ordering. */
+function reorderTree(entries, manifest) {
+	const pathIndex = new Map(manifest.map((m, i) => [m.path, i]));
+	entries.sort((a, b) => {
+		return (pathIndex.get(a.path) ?? Infinity) - (pathIndex.get(b.path) ?? Infinity);
+	});
+	for (const entry of entries) if (entry.children?.length) {
+		const manifestEntry = manifest.find((m) => m.path === entry.path);
+		if (manifestEntry?.children) reorderTree(entry.children, manifestEntry.children);
+	}
+}
 //#endregion
 //#region src/docs/sources/git.ts
 var DocsSourceGit = class extends DocsSource {
@@ -768,8 +795,9 @@ 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`. Directory stubs (`page === false`)
-* are skipped by default unless a custom `filter` is provided.
+* 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.
 *
 * A `README.md` table of contents is generated at the root of the output directory.
 */
@@ -777,13 +805,15 @@ async function exportDocsToFS(manager, dir, options = {}) {
 	const rootEntry = manager.flat.find((f) => f.entry.path === "/");
 	const tocLines = [`# ${options.title ?? rootEntry?.entry.title ?? "Table of Contents"}`, ""];
 	const writtenFiles = /* @__PURE__ */ new Set();
+	const dirPaths = /* @__PURE__ */ new Set();
+	collectDirPaths(manager.tree, dirPaths);
 	for (const flat of manager.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);
 		if (content === void 0) continue;
 		const cleanContent = options.plainText ? renderToText(content) : renderToMarkdown(content);
-		const filePath = flat.entry.path === "/" ? "/index.md" : flat.entry.path.endsWith(".md") ? flat.entry.path : `${flat.entry.path}.md`;
+		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 dest = join(dir, filePath);
 		await mkdir(dirname(dest), { recursive: true });
 		await writeFile(dest, cleanContent, "utf8");
@@ -795,6 +825,14 @@ 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) {
+	for (const entry of entries) if (entry.children?.length) {
+		set.add(entry.path);
+		collectDirPaths(entry.children, set);
+	}
 }
 //#endregion
 export { DocsSourceFS as a, DocsSourceGit as i, DocsSourceNpm as n, DocsSource as o, DocsSourceHTTP as r, DocsManager as s, exportDocsToFS as t };