@kekonic/diagrams-markdown-it 1.0.0-rc.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kekonic
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,17 @@
+# `@kekonic/diagrams-markdown-it`
+
+Render fenced `kdiagrams` blocks to static, accessible SVG in Markdown-it hosts.
+
+```ts
+import MarkdownIt from "markdown-it";
+import { kdiagramMarkdownIt, renderKDiagramMarkdown } from "@kekonic/diagrams-markdown-it";
+
+const md = new MarkdownIt();
+kdiagramMarkdownIt(md);
+const html = await renderKDiagramMarkdown(md, markdown);
+```
+
+KDiagram layout is asynchronous, so use `renderKDiagramMarkdown()` rather than calling
+`md.render()` directly. Static SVG with resolved theme tokens is the default. Diagnostics are
+available on `env.kdiagramDiagnostics` with both KDiagram source ranges and one-based Markdown
+lines.

package/dist/index.d.mts

@@ -0,0 +1,29 @@
+import { Diagnostic, RenderOptions } from "@kekonic/diagrams";
+import MarkdownIt from "markdown-it";
+
+//#region src/index.d.ts
+declare const RENDERED: unique symbol;
+type KDiagramFenceDiagnostic = Diagnostic & {
+  markdownLine: number;
+  markdownEndLine: number;
+};
+type KDiagramMarkdownEnvironment = {
+  [RENDERED]?: Map<number, string>;
+  kdiagramDiagnostics?: KDiagramFenceDiagnostic[];
+};
+type KDiagramMarkdownItOptions = {
+  className?: string;
+  renderOptions?: RenderOptions;
+  onDiagnostic?: (diagnostic: KDiagramFenceDiagnostic) => void;
+};
+/**
+ * Register the synchronous fence rule used by Markdown-it. Call
+ * {@link renderKDiagramMarkdown} to perform KDiagram's asynchronous layout pass before rendering.
+ */
+declare function kdiagramMarkdownIt(md: MarkdownIt, options?: KDiagramMarkdownItOptions): void;
+declare function renderKDiagramMarkdown(md: MarkdownIt, markdown: string, env?: KDiagramMarkdownEnvironment, options?: KDiagramMarkdownItOptions): Promise<string>;
+declare function isKDiagramFence(info: string): boolean;
+declare function encodeKDiagramFenceSource(source: string): string;
+//#endregion
+export { KDiagramFenceDiagnostic, KDiagramMarkdownEnvironment, KDiagramMarkdownItOptions, encodeKDiagramFenceSource, isKDiagramFence, kdiagramMarkdownIt, renderKDiagramMarkdown };
+//# sourceMappingURL=index.d.mts.map

package/dist/index.mjs

@@ -0,0 +1,70 @@
+import { escapeKDiagramAttribute, escapeKDiagramHtml, formatKDiagramBuildError, offsetKDiagramDiagnostic, renderKDiagramForBuild } from "@kekonic/diagrams-build";
+//#region src/index.ts
+const RENDERED = Symbol("kdiagram-rendered-fences");
+const REGISTERED_OPTIONS = /* @__PURE__ */ new WeakMap();
+/**
+* Register the synchronous fence rule used by Markdown-it. Call
+* {@link renderKDiagramMarkdown} to perform KDiagram's asynchronous layout pass before rendering.
+*/
+function kdiagramMarkdownIt(md, options = {}) {
+	REGISTERED_OPTIONS.set(md, options);
+	const fallback = md.renderer.rules.fence;
+	md.renderer.rules.fence = (tokens, index, renderOptions, env, self) => {
+		if (fenceLanguage(tokens[index]) !== "kdiagram") return fallback ? fallback(tokens, index, renderOptions, env, self) : self.renderToken(tokens, index, renderOptions);
+		const rendered = env[RENDERED]?.get(index);
+		if (rendered) return rendered;
+		return `<pre class="kdiagram-error"><code>KDiagram fence was not prepared. Use renderKDiagramMarkdown().</code></pre>`;
+	};
+}
+async function renderKDiagramMarkdown(md, markdown, env = {}, options = {}) {
+	const registered = REGISTERED_OPTIONS.get(md);
+	const effectiveOptions = {
+		...registered,
+		...options,
+		renderOptions: {
+			...registered?.renderOptions,
+			...options.renderOptions
+		}
+	};
+	const tokens = md.parse(markdown, env);
+	const rendered = /* @__PURE__ */ new Map();
+	const diagnostics = [];
+	await Promise.all(tokens.map(async (token, index) => {
+		if (fenceLanguage(token) !== "kdiagram") return;
+		const result = await renderKDiagramForBuild(token.content, { renderOptions: effectiveOptions.renderOptions });
+		const mapped = result.diagnostics.map((diagnostic) => mapDiagnostic(token, diagnostic));
+		diagnostics.push(...mapped);
+		for (const diagnostic of mapped) effectiveOptions.onDiagnostic?.(diagnostic);
+		if (result.svg) rendered.set(index, `<figure class="${escapeKDiagramAttribute(effectiveOptions.className ?? "k-diagram")}">${result.svg}</figure>`);
+		else {
+			const message = formatKDiagramBuildError(mapped);
+			rendered.set(index, `<pre class="kdiagram-error"><code>${escapeKDiagramHtml(message)}</code></pre>`);
+		}
+	}));
+	diagnostics.sort((a, b) => a.markdownLine - b.markdownLine || a.markdownEndLine - b.markdownEndLine);
+	env[RENDERED] = rendered;
+	env.kdiagramDiagnostics = diagnostics;
+	return md.renderer.render(tokens, md.options, env);
+}
+function fenceLanguage(token) {
+	if (!token || token.type !== "fence") return void 0;
+	return token.info.trim().split(/\s+/, 1)[0]?.toLowerCase();
+}
+function isKDiagramFence(info) {
+	return info.trim().split(/\s+/, 1)[0]?.toLowerCase() === "kdiagram";
+}
+function encodeKDiagramFenceSource(source) {
+	return encodeURIComponent(source);
+}
+function mapDiagnostic(token, diagnostic) {
+	const mapped = offsetKDiagramDiagnostic(diagnostic, (token.map?.[0] ?? 0) + 2);
+	return {
+		...diagnostic,
+		markdownLine: mapped.hostLine,
+		markdownEndLine: mapped.hostEndLine
+	};
+}
+//#endregion
+export { encodeKDiagramFenceSource, isKDiagramFence, kdiagramMarkdownIt, renderKDiagramMarkdown };
+
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.mjs","names":[],"sources":["../src/index.ts"],"sourcesContent":["import type { Diagnostic, RenderOptions } from \"@kekonic/diagrams\";\nimport {\n  escapeKDiagramAttribute,\n  escapeKDiagramHtml,\n  formatKDiagramBuildError,\n  offsetKDiagramDiagnostic,\n  renderKDiagramForBuild,\n} from \"@kekonic/diagrams-build\";\nimport type MarkdownIt from \"markdown-it\";\nimport type Token from \"markdown-it/lib/token.mjs\";\n\nconst RENDERED = Symbol(\"kdiagram-rendered-fences\");\nconst REGISTERED_OPTIONS = new WeakMap<MarkdownIt, KDiagramMarkdownItOptions>();\n\nexport type KDiagramFenceDiagnostic = Diagnostic & {\n  markdownLine: number;\n  markdownEndLine: number;\n};\n\nexport type KDiagramMarkdownEnvironment = {\n  [RENDERED]?: Map<number, string>;\n  kdiagramDiagnostics?: KDiagramFenceDiagnostic[];\n};\n\nexport type KDiagramMarkdownItOptions = {\n  className?: string;\n  renderOptions?: RenderOptions;\n  onDiagnostic?: (diagnostic: KDiagramFenceDiagnostic) => void;\n};\n\n/**\n * Register the synchronous fence rule used by Markdown-it. Call\n * {@link renderKDiagramMarkdown} to perform KDiagram's asynchronous layout pass before rendering.\n */\nexport function kdiagramMarkdownIt(md: MarkdownIt, options: KDiagramMarkdownItOptions = {}): void {\n  REGISTERED_OPTIONS.set(md, options);\n  const fallback = md.renderer.rules.fence;\n  md.renderer.rules.fence = (tokens, index, renderOptions, env, self) => {\n    if (fenceLanguage(tokens[index]) !== \"kdiagram\") {\n      return fallback\n        ? fallback(tokens, index, renderOptions, env, self)\n        : self.renderToken(tokens, index, renderOptions);\n    }\n    const rendered = (env as KDiagramMarkdownEnvironment)[RENDERED]?.get(index);\n    if (rendered) return rendered;\n    return `<pre class=\"kdiagram-error\"><code>KDiagram fence was not prepared. Use renderKDiagramMarkdown().</code></pre>`;\n  };\n}\n\nexport async function renderKDiagramMarkdown(\n  md: MarkdownIt,\n  markdown: string,\n  env: KDiagramMarkdownEnvironment = {},\n  options: KDiagramMarkdownItOptions = {},\n): Promise<string> {\n  const registered = REGISTERED_OPTIONS.get(md);\n  const effectiveOptions: KDiagramMarkdownItOptions = {\n    ...registered,\n    ...options,\n    renderOptions: { ...registered?.renderOptions, ...options.renderOptions },\n  };\n  const tokens = md.parse(markdown, env);\n  const rendered = new Map<number, string>();\n  const diagnostics: KDiagramFenceDiagnostic[] = [];\n\n  await Promise.all(\n    tokens.map(async (token, index) => {\n      if (fenceLanguage(token) !== \"kdiagram\") return;\n      const result = await renderKDiagramForBuild(token.content, {\n        renderOptions: effectiveOptions.renderOptions,\n      });\n      const mapped = result.diagnostics.map((diagnostic) => mapDiagnostic(token, diagnostic));\n      diagnostics.push(...mapped);\n      for (const diagnostic of mapped) effectiveOptions.onDiagnostic?.(diagnostic);\n      if (result.svg) {\n        rendered.set(\n          index,\n          `<figure class=\"${escapeKDiagramAttribute(effectiveOptions.className ?? \"k-diagram\")}\">${result.svg}</figure>`,\n        );\n      } else {\n        const message = formatKDiagramBuildError(mapped);\n        rendered.set(\n          index,\n          `<pre class=\"kdiagram-error\"><code>${escapeKDiagramHtml(message)}</code></pre>`,\n        );\n      }\n    }),\n  );\n\n  diagnostics.sort(\n    (a, b) => a.markdownLine - b.markdownLine || a.markdownEndLine - b.markdownEndLine,\n  );\n  env[RENDERED] = rendered;\n  env.kdiagramDiagnostics = diagnostics;\n  return md.renderer.render(tokens, md.options, env);\n}\n\nfunction fenceLanguage(token: Token | undefined): string | undefined {\n  if (!token || token.type !== \"fence\") return undefined;\n  return token.info.trim().split(/\\s+/, 1)[0]?.toLowerCase();\n}\n\nexport function isKDiagramFence(info: string): boolean {\n  return info.trim().split(/\\s+/, 1)[0]?.toLowerCase() === \"kdiagram\";\n}\n\nexport function encodeKDiagramFenceSource(source: string): string {\n  return encodeURIComponent(source);\n}\n\nfunction mapDiagnostic(token: Token, diagnostic: Diagnostic): KDiagramFenceDiagnostic {\n  const contentStart = (token.map?.[0] ?? 0) + 2;\n  const mapped = offsetKDiagramDiagnostic(diagnostic, contentStart);\n  return {\n    ...diagnostic,\n    markdownLine: mapped.hostLine,\n    markdownEndLine: mapped.hostEndLine,\n  };\n}\n"],"mappings":";;AAWA,MAAM,WAAW,OAAO,0BAA0B;AAClD,MAAM,qCAAqB,IAAI,QAA+C;;;;;AAsB9E,SAAgB,mBAAmB,IAAgB,UAAqC,CAAC,GAAS;CAChG,mBAAmB,IAAI,IAAI,OAAO;CAClC,MAAM,WAAW,GAAG,SAAS,MAAM;CACnC,GAAG,SAAS,MAAM,SAAS,QAAQ,OAAO,eAAe,KAAK,SAAS;EACrE,IAAI,cAAc,OAAO,MAAM,MAAM,YACnC,OAAO,WACH,SAAS,QAAQ,OAAO,eAAe,KAAK,IAAI,IAChD,KAAK,YAAY,QAAQ,OAAO,aAAa;EAEnD,MAAM,WAAY,IAAoC,SAAS,EAAE,IAAI,KAAK;EAC1E,IAAI,UAAU,OAAO;EACrB,OAAO;CACT;AACF;AAEA,eAAsB,uBACpB,IACA,UACA,MAAmC,CAAC,GACpC,UAAqC,CAAC,GACrB;CACjB,MAAM,aAAa,mBAAmB,IAAI,EAAE;CAC5C,MAAM,mBAA8C;EAClD,GAAG;EACH,GAAG;EACH,eAAe;GAAE,GAAG,YAAY;GAAe,GAAG,QAAQ;EAAc;CAC1E;CACA,MAAM,SAAS,GAAG,MAAM,UAAU,GAAG;CACrC,MAAM,2BAAW,IAAI,IAAoB;CACzC,MAAM,cAAyC,CAAC;CAEhD,MAAM,QAAQ,IACZ,OAAO,IAAI,OAAO,OAAO,UAAU;EACjC,IAAI,cAAc,KAAK,MAAM,YAAY;EACzC,MAAM,SAAS,MAAM,uBAAuB,MAAM,SAAS,EACzD,eAAe,iBAAiB,cAClC,CAAC;EACD,MAAM,SAAS,OAAO,YAAY,KAAK,eAAe,cAAc,OAAO,UAAU,CAAC;EACtF,YAAY,KAAK,GAAG,MAAM;EAC1B,KAAK,MAAM,cAAc,QAAQ,iBAAiB,eAAe,UAAU;EAC3E,IAAI,OAAO,KACT,SAAS,IACP,OACA,kBAAkB,wBAAwB,iBAAiB,aAAa,WAAW,EAAE,IAAI,OAAO,IAAI,UACtG;OACK;GACL,MAAM,UAAU,yBAAyB,MAAM;GAC/C,SAAS,IACP,OACA,qCAAqC,mBAAmB,OAAO,EAAE,cACnE;EACF;CACF,CAAC,CACH;CAEA,YAAY,MACT,GAAG,MAAM,EAAE,eAAe,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,eACrE;CACA,IAAI,YAAY;CAChB,IAAI,sBAAsB;CAC1B,OAAO,GAAG,SAAS,OAAO,QAAQ,GAAG,SAAS,GAAG;AACnD;AAEA,SAAS,cAAc,OAA8C;CACnE,IAAI,CAAC,SAAS,MAAM,SAAS,SAAS,OAAO,KAAA;CAC7C,OAAO,MAAM,KAAK,KAAK,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,YAAY;AAC3D;AAEA,SAAgB,gBAAgB,MAAuB;CACrD,OAAO,KAAK,KAAK,CAAC,CAAC,MAAM,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,YAAY,MAAM;AAC3D;AAEA,SAAgB,0BAA0B,QAAwB;CAChE,OAAO,mBAAmB,MAAM;AAClC;AAEA,SAAS,cAAc,OAAc,YAAiD;CAEpF,MAAM,SAAS,yBAAyB,aADlB,MAAM,MAAM,MAAM,KAAK,CACmB;CAChE,OAAO;EACL,GAAG;EACH,cAAc,OAAO;EACrB,iBAAiB,OAAO;CAC1B;AACF"}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@kekonic/diagrams-markdown-it",
+  "version": "1.0.0-rc.4",
+  "description": "Static KDiagram diagrams for Markdown-it hosts.",
+  "keywords": [
+    "diagram",
+    "kdiagram",
+    "markdown-it",
+    "vitepress"
+  ],
+  "homepage": "https://github.com/kekonic/diagrams#readme",
+  "bugs": {
+    "url": "https://github.com/kekonic/diagrams/issues"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kekonic/diagrams.git",
+    "directory": "packages/diagrams-markdown-it"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@kekonic/diagrams": "1.0.0-rc.4",
+    "@kekonic/diagrams-build": "1.0.0-rc.4"
+  },
+  "devDependencies": {
+    "@types/markdown-it": "^14.1.2",
+    "markdown-it": "^14.1.0",
+    "typescript": "^5",
+    "vitest": "^4"
+  },
+  "peerDependencies": {
+    "markdown-it": ">=14"
+  },
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "scripts": {
+    "build": "vp pack",
+    "test": "vp test"
+  }
+}