@vezham/docs-core 1.0.1

package/dist/mdx-plugins/remark-llms.js

@@ -0,0 +1,338 @@
+import { i as toMdxExport } from "../utils-Yx0IL9eW.js";
+import { defaultStringifier } from "./stringifier.js";
+import { defaultHandlers } from "mdast-util-to-markdown";
+//#region src/mdx-plugins/remark-llms.ts
+/**
+* generate `llms.txt` for markdown.
+*/
+function remarkLLMs({ as = "_markdown", headingIds = true, _data = false, mdxAsPlaceholder, output = "string", ...rest } = {}) {
+	const jsx = output === "function";
+	const stringifier = defaultStringifier({
+		...rest,
+		filterElement(node) {
+			switch (node.type) {
+				case "mdxjsEsm": return false;
+				default: return true;
+			}
+		},
+		stringify(node, parent, state, info, collect) {
+			if (mdxAsPlaceholder && !collect) switch (node.type) {
+				case "mdxJsxFlowElement":
+				case "mdxJsxTextElement": if (node.name && mdxAsPlaceholder.includes(node.name)) return placeholder(node, parent, state, info);
+			}
+			const custom = rest.stringify?.(node, parent, state, info, void 0);
+			if (custom) return custom;
+			if (collect) return collectJsx(node, state, info, collect);
+		},
+		handlers: {
+			heading(node, _p, state, info) {
+				const id = node.data?.hProperties?.id;
+				const defaultValue = defaultHandlers.heading(node, _p, state, info);
+				return headingIds && id ? `${defaultValue} [#${id}]` : defaultValue;
+			},
+			...rest.handlers
+		}
+	});
+	return (node, file) => {
+		if (jsx) {
+			const collect = [];
+			const text = stringifier.call(this, node, collect);
+			node.children.unshift(jsxToEstree(as, toJsxChunks(text, collect)));
+			return;
+		}
+		const value = stringifier.call(this, node, void 0);
+		node.children.unshift(toMdxExport(as, value));
+		if (_data) file.data.markdown = value;
+	};
+}
+/**
+* Preserve AST data to render the MDX component at runtime, use `renderPlaceholder()` to render the placeholders.
+*/
+function placeholder(node, _parent, state, info) {
+	const attributes = {};
+	for (const attr of node.attributes) {
+		if (attr.type === "mdxJsxExpressionAttribute") continue;
+		attributes[attr.name] = attr.value;
+	}
+	return `\0${JSON.stringify({
+		name: node.name,
+		children: state.containerPhrasing(node, info),
+		attributes
+	})}\0`;
+}
+/**
+* `stringify` branch for the `function` output: collect the element and return a marker,
+* resolved later by `toJsxChunks()`. Only components (capitalized names) are kept.
+*/
+function collectJsx(node, state, info, collect) {
+	switch (node.type) {
+		case "mdxJsxFlowElement":
+		case "mdxJsxTextElement": {
+			if (!node.name || !/^[A-Z][\w$]*$/.test(node.name)) return;
+			const entry = {
+				node,
+				children: ""
+			};
+			const marker = `\0${collect.push(entry) - 1}\0`;
+			entry.children = node.type === "mdxJsxTextElement" ? state.containerPhrasing(node, info) : state.containerFlow(node, info);
+			return marker;
+		}
+	}
+}
+const Marker = /\0(\d+)\0/g;
+/**
+* Split stringified Markdown on the markers emitted by `collectJsx()` into
+* alternating text chunks and kept JSX elements, recursively for their children.
+*/
+function toJsxChunks(text, collect) {
+	const out = [];
+	let idx = 0;
+	for (const match of text.matchAll(Marker)) {
+		if (match.index > idx) out.push(text.slice(idx, match.index));
+		const { node, children } = collect[Number(match[1])];
+		out.push({
+			node,
+			children: toJsxChunks(children, collect)
+		});
+		idx = match.index + match[0].length;
+	}
+	if (idx < text.length) out.push(text.slice(idx));
+	return out;
+}
+/**
+* Generate the component export as an ESM node with estree, for the MDX.js compiler.
+*/
+function jsxToEstree(as, chunks) {
+	const hasJsx = chunks.some((chunk) => typeof chunk !== "string");
+	let value;
+	if (chunks.length === 0) value = literal("");
+	else if (typeof chunks[0] === "string" && chunks.length === 1) value = literal(chunks[0]);
+	else if (chunks.length === 1) value = elementToEstree(chunks[0]);
+	else value = {
+		type: "JSXFragment",
+		openingFragment: { type: "JSXOpeningFragment" },
+		closingFragment: { type: "JSXClosingFragment" },
+		children: childrenToEstree(chunks)
+	};
+	const body = [{
+		type: "IfStatement",
+		test: {
+			type: "UnaryExpression",
+			operator: "!",
+			prefix: true,
+			argument: {
+				type: "CallExpression",
+				callee: {
+					type: "Identifier",
+					name: "_asMarkdown"
+				},
+				arguments: [],
+				optional: false
+			}
+		},
+		consequent: {
+			type: "ReturnStatement",
+			argument: literal(null)
+		},
+		alternate: null
+	}];
+	if (hasJsx) body.push({
+		type: "VariableDeclaration",
+		kind: "const",
+		declarations: [{
+			type: "VariableDeclarator",
+			id: {
+				type: "Identifier",
+				name: "_c"
+			},
+			init: {
+				type: "CallExpression",
+				callee: {
+					type: "Identifier",
+					name: "_jsxComponents"
+				},
+				arguments: [{
+					type: "MemberExpression",
+					object: {
+						type: "Identifier",
+						name: "props"
+					},
+					property: {
+						type: "Identifier",
+						name: "components"
+					},
+					computed: false,
+					optional: false
+				}],
+				optional: false
+			}
+		}]
+	});
+	body.push({
+		type: "ReturnStatement",
+		argument: value
+	});
+	return {
+		type: "mdxjsEsm",
+		value: "",
+		data: { estree: {
+			type: "Program",
+			sourceType: "module",
+			body: [{
+				type: "ImportDeclaration",
+				attributes: [],
+				specifiers: [{
+					type: "ImportSpecifier",
+					imported: {
+						type: "Identifier",
+						name: "asMarkdown"
+					},
+					local: {
+						type: "Identifier",
+						name: "_asMarkdown"
+					}
+				}, ...hasJsx ? [{
+					type: "ImportSpecifier",
+					imported: {
+						type: "Identifier",
+						name: "jsxComponents"
+					},
+					local: {
+						type: "Identifier",
+						name: "_jsxComponents"
+					}
+				}] : []],
+				source: literal("@vezham/docs-core/server")
+			}, {
+				type: "ExportNamedDeclaration",
+				attributes: [],
+				specifiers: [],
+				declaration: {
+					type: "FunctionDeclaration",
+					id: {
+						type: "Identifier",
+						name: as
+					},
+					params: [{
+						type: "Identifier",
+						name: "props"
+					}],
+					body: {
+						type: "BlockStatement",
+						body
+					}
+				}
+			}]
+		} }
+	};
+}
+function literal(value) {
+	return {
+		type: "Literal",
+		value
+	};
+}
+function childrenToEstree(chunks) {
+	const out = [];
+	for (const chunk of chunks) out.push(typeof chunk === "string" ? {
+		type: "JSXExpressionContainer",
+		expression: literal(chunk)
+	} : elementToEstree(chunk));
+	return out;
+}
+function elementToEstree({ node, children }) {
+	const attributes = [];
+	for (const attr of node.attributes) {
+		if (attr.type === "mdxJsxExpressionAttribute") {
+			const expression = programExpression(attr.data?.estree);
+			if (expression?.type === "ObjectExpression" && expression.properties.length === 1 && expression.properties[0].type === "SpreadElement") attributes.push({
+				type: "JSXSpreadAttribute",
+				argument: expression.properties[0].argument
+			});
+			continue;
+		}
+		let value = null;
+		if (typeof attr.value === "string") value = {
+			type: "Literal",
+			value: attr.value
+		};
+		else if (attr.value) {
+			const expression = programExpression(attr.value.data?.estree);
+			if (!expression) continue;
+			value = {
+				type: "JSXExpressionContainer",
+				expression
+			};
+		}
+		attributes.push({
+			type: "JSXAttribute",
+			name: attr.name.includes(":") ? {
+				type: "JSXNamespacedName",
+				namespace: {
+					type: "JSXIdentifier",
+					name: attr.name.slice(0, attr.name.indexOf(":"))
+				},
+				name: {
+					type: "JSXIdentifier",
+					name: attr.name.slice(attr.name.indexOf(":") + 1)
+				}
+			} : {
+				type: "JSXIdentifier",
+				name: attr.name
+			},
+			value
+		});
+	}
+	const name = {
+		type: "JSXMemberExpression",
+		object: {
+			type: "JSXIdentifier",
+			name: "_c"
+		},
+		property: {
+			type: "JSXIdentifier",
+			name: node.name
+		}
+	};
+	const element = {
+		type: "JSXElement",
+		openingElement: {
+			type: "JSXOpeningElement",
+			name,
+			attributes,
+			selfClosing: children.length === 0
+		},
+		closingElement: children.length === 0 ? null : {
+			type: "JSXClosingElement",
+			name
+		},
+		children: childrenToEstree(children)
+	};
+	if (node.type === "mdxJsxFlowElement") return element;
+	return {
+		type: "JSXElement",
+		openingElement: {
+			type: "JSXOpeningElement",
+			name: {
+				type: "JSXIdentifier",
+				name: "span"
+			},
+			attributes: [],
+			selfClosing: false
+		},
+		closingElement: {
+			type: "JSXClosingElement",
+			name: {
+				type: "JSXIdentifier",
+				name: "span"
+			}
+		},
+		children: [element]
+	};
+}
+function programExpression(program) {
+	const statement = program?.body[0];
+	if (statement?.type === "ExpressionStatement") return statement.expression;
+}
+//#endregion
+export { placeholder, remarkLLMs };

package/dist/mdx-plugins/remark-llms.runtime.d.ts

@@ -0,0 +1,10 @@
+import { t as Awaitable } from "../types-D89QoQR-.js";
+//#region src/mdx-plugins/remark-llms.runtime.d.ts
+interface PlaceholderData {
+  name: string | null;
+  attributes: Record<string, unknown>;
+  children: string;
+}
+declare function renderPlaceholder(text: string, renderers: Record<string, (data: PlaceholderData) => Awaitable<string>>): Promise<string>;
+//#endregion
+export { PlaceholderData, renderPlaceholder };

package/dist/mdx-plugins/remark-llms.runtime.js

@@ -0,0 +1,24 @@
+//#region src/mdx-plugins/remark-llms.runtime.ts
+const regex = /\0(.+?)\0/gs;
+async function renderPlaceholder(text, renderers) {
+	let out = "";
+	let idx = 0;
+	for (const match of text.matchAll(regex)) {
+		out += text.slice(idx, match.index);
+		const inner = match[1];
+		try {
+			const data = JSON.parse(inner);
+			const renderer = data.name && renderers[data.name];
+			if (data.children.trim()) data.children = await renderPlaceholder(data.children, renderers);
+			if (renderer) out += await renderer(data);
+			else out += data.children;
+		} catch {
+			out += match[0];
+		}
+		idx = match.index + match[0].length;
+	}
+	out += text.slice(idx);
+	return out;
+}
+//#endregion
+export { renderPlaceholder };

package/dist/mdx-plugins/remark-mdx-files.d.ts

@@ -0,0 +1,2 @@
+import { a as remarkMdxFiles, i as ToMdxOptions, n as FolderNode, r as RemarkMdxFilesOptions, t as FileNode } from "../remark-mdx-files-Buvxc-sa.js";
+export { FileNode, FolderNode, RemarkMdxFilesOptions, ToMdxOptions, remarkMdxFiles };

package/dist/mdx-plugins/remark-mdx-files.js

@@ -0,0 +1,182 @@
+import { visit } from "unist-util-visit";
+import path from "node:path";
+//#region src/mdx-plugins/remark-mdx-files.ts
+function parseFileTree(code) {
+	const lines = code.split(/\r?\n/);
+	const stack = /* @__PURE__ */ new Map();
+	for (const line of lines) {
+		let depth = 0;
+		let name = line;
+		let match;
+		while (match = /(?:├──|│|└──)\s*/.exec(name)) {
+			name = name.slice(match[0].length);
+			depth++;
+		}
+		if (!name) continue;
+		const node = name.endsWith("/") ? {
+			type: "folder",
+			name,
+			children: [],
+			depth
+		} : {
+			type: "file",
+			name,
+			depth
+		};
+		let parent;
+		for (let i = depth - 1; i >= 0 && !parent; i--) parent = stack.get(i);
+		stack.set(depth, node);
+		if (!parent) continue;
+		if (parent.type === "file") Object.assign(parent, {
+			type: "folder",
+			children: []
+		});
+		parent.children.push(node);
+	}
+	return stack.get(0);
+}
+function defaultToMDX(node, options, depth = 0) {
+	if (depth === 0) return {
+		type: "mdxJsxFlowElement",
+		name: "Files",
+		attributes: [],
+		children: [defaultToMDX(node, options, depth + 1)]
+	};
+	const attributes = [{
+		type: "mdxJsxAttribute",
+		name: "name",
+		value: node.name
+	}];
+	if (node.type === "file") return {
+		type: "mdxJsxFlowElement",
+		attributes,
+		children: [],
+		name: "File"
+	};
+	if (options.defaultOpenAll) attributes.push({
+		type: "mdxJsxAttribute",
+		name: "defaultOpen",
+		value: null
+	});
+	return {
+		type: "mdxJsxFlowElement",
+		attributes,
+		name: "Folder",
+		children: node.children.map((item) => defaultToMDX(item, options, depth + 1))
+	};
+}
+/**
+*
+* **Files CodeBlock:**
+*
+* Convert codeblocks with `files` as lang, like:
+*
+* ```files
+* project
+* ├── src
+* │   ├── index.js
+* │   └── utils
+* │       └── helper.js
+* ├── package.json
+* ```
+*
+* into MDX `<Files />` component.
+*
+* **Auto Files:**
+*
+* Generates MDX `<Files />` component from file system.
+*
+* ```mdx
+* <auto-files dir="scripts" pattern="my-dir/*" defaultOpenAll />
+* ```
+*/
+function remarkMdxFiles(options = {}) {
+	const { lang = "files", toMdx = defaultToMDX } = options;
+	async function autoFiles(file, node, { patterns, dir, defaultOpenAll = false }) {
+		const { glob } = await import("tinyglobby");
+		if (!patterns) file.fail("Missing `pattern` prop in <auto-files>", { place: node.position });
+		const baseDir = file.dirname ?? file.cwd;
+		const cwd = dir ? path.join(baseDir, dir) : baseDir;
+		const files = await glob(patterns, { cwd });
+		Object.assign(node, toMdx(buildFileTreeFromGlob(cwd, files), { defaultOpenAll }));
+	}
+	return async (tree, file) => {
+		const queue = [];
+		visit(tree, ["code", "mdxJsxFlowElement"], (node) => {
+			if (node.type === "code") {
+				if (node.lang !== lang || !node.value) return;
+				const fileTree = parseFileTree(node.value);
+				if (!fileTree) return;
+				Object.assign(node, toMdx(fileTree, { defaultOpenAll: true }));
+				return "skip";
+			}
+			if (node.type === "mdxJsxFlowElement") {
+				if (node.name !== "auto-files") return;
+				const parsed = {};
+				for (const attr of node.attributes) {
+					if (attr.type !== "mdxJsxAttribute") continue;
+					const { name, value } = attr;
+					switch (name) {
+						case "dir":
+							if (typeof value === "string") parsed.dir = value;
+							break;
+						case "pattern":
+							if (typeof value === "string") {
+								parsed.patterns ??= [];
+								parsed.patterns.push(value);
+							}
+							break;
+						case "defaultOpenAll": parsed.defaultOpenAll = true;
+					}
+				}
+				queue.push(autoFiles(file, node, parsed));
+				return "skip";
+			}
+		});
+		await Promise.all(queue);
+	};
+}
+function buildFileTreeFromGlob(dir, files) {
+	const nodeMap = /* @__PURE__ */ new Map();
+	const root = {
+		depth: 0,
+		type: "folder",
+		name: path.basename(dir),
+		children: []
+	};
+	nodeMap.set("", root);
+	for (const file of files) {
+		const parts = path.normalize(file).split(path.sep).filter((part) => part.length > 0);
+		let currentPath = "";
+		let current = root;
+		for (let i = 0; i < parts.length; i++) {
+			const name = parts[i];
+			const nextPath = path.join(currentPath, name);
+			if (i === parts.length - 1) {
+				const fileNode = {
+					depth: i + 1,
+					type: "file",
+					name
+				};
+				current.children.push(fileNode);
+			} else {
+				let folder = nodeMap.get(nextPath);
+				if (!folder) {
+					folder = {
+						depth: i + 1,
+						type: "folder",
+						name,
+						children: []
+					};
+					nodeMap.set(nextPath, folder);
+					current.children.push(folder);
+				}
+				current = folder;
+				currentPath = nextPath;
+			}
+		}
+	}
+	return root;
+}
+//#endregion
+export { remarkMdxFiles };

package/dist/mdx-plugins/remark-mdx-mermaid.d.ts

@@ -0,0 +1,2 @@
+import { n as remarkMdxMermaid, t as RemarkMdxMermaidOptions } from "../remark-mdx-mermaid-C1bCHHc6.js";
+export { RemarkMdxMermaidOptions, remarkMdxMermaid };

package/dist/mdx-plugins/remark-mdx-mermaid.js

@@ -0,0 +1,28 @@
+import { visit } from "unist-util-visit";
+//#region src/mdx-plugins/remark-mdx-mermaid.ts
+function toMDX(code) {
+	return {
+		type: "mdxJsxFlowElement",
+		name: "Mermaid",
+		attributes: [{
+			type: "mdxJsxAttribute",
+			name: "chart",
+			value: code.trim()
+		}],
+		children: []
+	};
+}
+/**
+* Convert `mermaid` codeblocks into `<Mermaid />` MDX component
+*/
+function remarkMdxMermaid(options = {}) {
+	const { lang = "mermaid" } = options;
+	return (tree) => {
+		visit(tree, "code", (node, idx, parent) => {
+			if (node.lang !== lang || !node.value || typeof idx !== "number" || !parent) return;
+			parent.children[idx] = toMDX(node.value);
+		});
+	};
+}
+//#endregion
+export { remarkMdxMermaid };

package/dist/mdx-plugins/remark-npm.d.ts

@@ -0,0 +1,2 @@
+import { n as remarkNpm, t as RemarkNpmOptions } from "../remark-npm-BbpvkJaT.js";
+export { RemarkNpmOptions, remarkNpm };

package/dist/mdx-plugins/remark-npm.js

@@ -0,0 +1,76 @@
+import { generateCodeBlockTabs } from "./codeblock-utils.js";
+import { visit } from "unist-util-visit";
+import convert from "npm-to-yarn";
+//#region src/mdx-plugins/remark-npm.ts
+function convertLines(cmd, to) {
+	return cmd.split("\n").map((l) => convert(l, to)).join("\n");
+}
+/**
+* It generates multiple tabs of codeblocks for different package managers from a npm command codeblock.
+*/
+function remarkNpm({ persist = false, packageManagers = [
+	{
+		command: (cmd) => cmd,
+		name: "npm"
+	},
+	{
+		command: (cmd) => convertLines(cmd, "pnpm"),
+		name: "pnpm"
+	},
+	{
+		command: (cmd) => convertLines(cmd, "yarn"),
+		name: "yarn"
+	},
+	{
+		command: (cmd) => convertLines(cmd, "bun"),
+		name: "bun"
+	}
+] } = {}) {
+	return (tree) => {
+		visit(tree, "code", (node, idx, parent) => {
+			if (typeof idx !== "number" || !parent) return;
+			let code;
+			switch (node.lang) {
+				case "package-install":
+					code = node.value;
+					if (!code.startsWith("npm") && !code.startsWith("npx")) code = `npm install ${code}`;
+					break;
+				case "npm":
+					code = node.value;
+					break;
+				default: return;
+			}
+			const options = {
+				persist,
+				tabs: [],
+				triggers: []
+			};
+			for (const manager of packageManagers) {
+				const value = manager.value ?? manager.name;
+				const command = manager.command(code);
+				if (!command || command.length === 0) continue;
+				options.defaultValue ??= value;
+				options.triggers.push({
+					value,
+					children: [{
+						type: "text",
+						value: manager.name
+					}]
+				});
+				options.tabs.push({
+					value,
+					children: [{
+						type: "code",
+						lang: "bash",
+						meta: node.meta,
+						value: command
+					}]
+				});
+			}
+			parent.children[idx] = generateCodeBlockTabs(options);
+			return "skip";
+		});
+	};
+}
+//#endregion
+export { remarkNpm };

package/dist/mdx-plugins/remark-steps.d.ts

@@ -0,0 +1,2 @@
+import { n as remarkSteps, t as RemarkStepsOptions } from "../remark-steps-DqVEo0iq.js";
+export { RemarkStepsOptions, remarkSteps };