mdzilla 0.0.2 → 0.0.4

package/dist/_chunks/exporter.mjs

@@ -1,6 +1,6 @@
 import { mkdir, readFile, readdir, stat, writeFile } from "node:fs/promises";
 import { basename, dirname, extname, join } from "node:path";
-import { parseMeta, renderToText } from "md4x";
+import { parseMeta, renderToMarkdown, renderToText } from "md4x";
 import { existsSync } from "node:fs";
 import { tmpdir } from "node:os";
 //#region src/docs/manager.ts
@@ -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 {
@@ -763,25 +790,49 @@ async function npmProvider(input) {
 }
 //#endregion
 //#region src/docs/exporter.ts
-var DocsExporter = class {};
-var DocsExporterFS = class extends DocsExporter {
-	dir;
-	constructor(dir) {
-		super();
-		this.dir = dir;
-	}
-	async export(manager, options = {}) {
-		for (const flat of manager.flat) {
-			if (!options.includeStubs && flat.entry.page === false) continue;
-			let content = await manager.getContent(flat);
-			if (content === void 0) continue;
-			if (options.plainText) content = renderToText(content);
-			const filePath = flat.entry.path === "/" ? "/index.md" : `${flat.entry.path}.md`;
-			const dest = join(this.dir, filePath);
-			await mkdir(dirname(dest), { recursive: true });
-			await writeFile(dest, content, "utf8");
-		}
+/** 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.
+*
+* 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 === "/");
+	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 === "/" || 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");
+		writtenFiles.add(filePath.slice(1));
+		const indent = "  ".repeat(flat.depth);
+		const desc = flat.entry.description ? `: ${flat.entry.description}` : "";
+		tocLines.push(`${indent}- [${flat.entry.title}](.${filePath})${desc}`);
+	}
+	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 { DocsSourceGit as a, DocsManager as c, DocsSourceHTTP as i, DocsExporterFS as n, DocsSourceFS as o, DocsSourceNpm as r, DocsSource as s, DocsExporter as t };
+export { DocsSourceFS as a, DocsSourceGit as i, DocsSourceNpm as n, DocsSource as o, DocsSourceHTTP as r, DocsManager as s, exportDocsToFS as t };

package/dist/cli/main.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { a as DocsSourceGit, c as DocsManager, i as DocsSourceHTTP, n as DocsExporterFS, o as DocsSourceFS, r as DocsSourceNpm } from "../_chunks/exporter.mjs";
+import { a as DocsSourceFS, i as DocsSourceGit, n as DocsSourceNpm, r as DocsSourceHTTP, s as DocsManager, t as exportDocsToFS } from "../_chunks/exporter.mjs";
 import { readFile } from "node:fs/promises";
 import { basename } from "node:path";
 import { parseMeta, renderToAnsi, renderToText } from "md4x";
@@ -765,7 +765,7 @@ async function main() {
 	const docs = new DocsManager(isURL ? new DocsSourceHTTP(docsDir) : docsDir.startsWith("gh:") ? new DocsSourceGit(docsDir) : docsDir.startsWith("npm:") ? new DocsSourceNpm(docsDir) : new DocsSourceFS(docsDir));
 	await docs.load();
 	if (exportDir) {
-		await new DocsExporterFS(exportDir).export(docs, { plainText: plain });
+		await exportDocsToFS(docs, exportDir, { plainText: plain });
 		console.log(`Exported ${docs.pages.length} pages to ${exportDir}`);
 		return;
 	}

package/dist/index.d.mts

@@ -144,18 +144,24 @@ declare class DocsManager {
 //#endregion
 //#region src/docs/exporter.d.ts
 interface ExportOptions {
-  /** Include entries where page === false (directory stubs). Default: false */
-  includeStubs?: boolean;
+  /** Custom filter callback. Return false to skip an entry. Default: skip stubs (page === false) */
+  filter?: (entry: FlatEntry) => boolean;
   /** Compile markdown to plain text using md4x. Default: false */
   plainText?: boolean;
+  /** Filename for the generated table of contents. Default: "README.md" */
+  tocFile?: string;
+  /** Title for the table of contents. Default: root entry title or "Table of Contents" */
+  title?: string;
 }
-declare abstract class DocsExporter {
-  abstract export(manager: DocsManager, options?: ExportOptions): Promise<void>;
-}
-declare class DocsExporterFS extends DocsExporter {
-  dir: string;
-  constructor(dir: string);
-  export(manager: DocsManager, options?: ExportOptions): Promise<void>;
-}
+/**
+ * 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.
+ *
+ * A `README.md` table of contents is generated at the root of the output directory.
+ */
+declare function exportDocsToFS(manager: DocsManager, dir: string, options?: ExportOptions): Promise<void>;
 //#endregion
-export { DocsExporter, DocsExporterFS, DocsManager, DocsSource, DocsSourceFS, DocsSourceGit, type DocsSourceGitOptions, DocsSourceHTTP, type DocsSourceHTTPOptions, DocsSourceNpm, type DocsSourceNpmOptions, type ExportOptions, type FlatEntry, type NavEntry };
+export { DocsManager, DocsSource, DocsSourceFS, DocsSourceGit, type DocsSourceGitOptions, DocsSourceHTTP, type DocsSourceHTTPOptions, DocsSourceNpm, type DocsSourceNpmOptions, type ExportOptions, type FlatEntry, type NavEntry, exportDocsToFS };

package/dist/index.mjs

@@ -1,2 +1,2 @@
-import { a as DocsSourceGit, c as DocsManager, i as DocsSourceHTTP, n as DocsExporterFS, o as DocsSourceFS, r as DocsSourceNpm, s as DocsSource, t as DocsExporter } from "./_chunks/exporter.mjs";
-export { DocsExporter, DocsExporterFS, DocsManager, DocsSource, DocsSourceFS, DocsSourceGit, DocsSourceHTTP, DocsSourceNpm };
+import { a as DocsSourceFS, i as DocsSourceGit, n as DocsSourceNpm, o as DocsSource, r as DocsSourceHTTP, s as DocsManager, t as exportDocsToFS } from "./_chunks/exporter.mjs";
+export { DocsManager, DocsSource, DocsSourceFS, DocsSourceGit, DocsSourceHTTP, DocsSourceNpm, exportDocsToFS };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mdzilla",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "",
   "license": "MIT",
   "repository": "pi0/mdzilla",
@@ -32,7 +32,7 @@
   "dependencies": {
     "@speed-highlight/core": "^1.2.14",
     "giget": "^3.1.2",
-    "md4x": ">=0.0.21",
+    "md4x": ">=0.0.22",
     "mdream": "^0.16.0",
     "std-env": "4.0.0-rc.1"
   },