kontexta 4.3.1

package/bundle/standalone/node_modules/kxta-publish/dist/render/blocks/glossary.js

@@ -0,0 +1,42 @@
+import yaml from "js-yaml";
+import { slugify } from "kxta-core";
+function escapeHtml(s) {
+    return s
+        .replace(/&/g, "&")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;")
+        .replace(/'/g, "&#39;");
+}
+export function renderGlossary(body, env) {
+    let parsed;
+    try {
+        parsed = yaml.load(body);
+    }
+    catch (e) {
+        throw new Error(`Invalid YAML in glossary block: ${e.message}`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new Error("glossary block must be a YAML list of {term, definition}");
+    }
+    const seen = new Set();
+    const terms = parsed.map((t) => {
+        const term = String(t.term ?? "");
+        const definition = String(t.definition ?? "");
+        let id = slugify(term).toLowerCase() || "term";
+        let n = 2;
+        while (seen.has(id))
+            id = `${slugify(term).toLowerCase() || "term"}-${n++}`;
+        seen.add(id);
+        return { id, term, definition };
+    });
+    if (env) {
+        env.terms = env.terms ?? [];
+        env.terms.push(...terms);
+    }
+    const items = terms.map((t) => `<div class="glossary-item" id="${t.id}">
+  <div class="glossary-term">${escapeHtml(t.term)}</div>
+  <div class="glossary-def">${escapeHtml(t.definition)}</div>
+</div>`);
+    return `<div class="glossary-grid">${items.join("\n")}</div>`;
+}

package/bundle/standalone/node_modules/kxta-publish/dist/render/blocks/mermaid.d.ts

@@ -0,0 +1,2 @@
+/** Render a mermaid source string into the zoomable/fullscreen-able wrapper. */
+export declare function renderMermaid(source: string, id: string): string;

package/bundle/standalone/node_modules/kxta-publish/dist/render/blocks/mermaid.js

@@ -0,0 +1,17 @@
+function escapeHtml(s) {
+    return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+/** Render a mermaid source string into the zoomable/fullscreen-able wrapper. */
+export function renderMermaid(source, id) {
+    const body = escapeHtml(source);
+    return `<div class="mermaid-wrap" id="${id}-wrap">
+  <div class="mermaid-zoom-bar">
+    <span class="mermaid-zoom-level" id="${id}-level">100%</span>
+    <button type="button" onclick="zoomDiagram('${id}', -0.15)" title="Zoom out">−</button>
+    <button type="button" onclick="zoomDiagram('${id}', 0.15)" title="Zoom in">+</button>
+    <button type="button" onclick="zoomDiagram('${id}', 0)" title="Reset">⟳</button>
+    <button type="button" onclick="toggleDiagramFullscreen('${id}-wrap')" title="Toggle fullscreen" id="${id}-fs">⛶</button>
+  </div>
+  <div class="mermaid-stage" id="${id}"><pre class="mermaid">${body}</pre></div>
+</div>`;
+}

package/bundle/standalone/node_modules/kxta-publish/dist/render/llms.d.ts

@@ -0,0 +1,3 @@
+import type { RenderedDoc, SearchEntry } from "../types.js";
+/** Generate an llms.txt file for LLM-readable documentation. */
+export declare function generateLlmsTxt(docs: RenderedDoc[], search: SearchEntry[], siteTitle: string): string;

package/bundle/standalone/node_modules/kxta-publish/dist/render/llms.js

@@ -0,0 +1,52 @@
+/** Generate an llms.txt file for LLM-readable documentation. */
+export function generateLlmsTxt(docs, search, siteTitle) {
+    const lines = [
+        `# ${siteTitle} - LLM-Readable Documentation`,
+        ``,
+        `This documentation is optimized for both human readers and LLM agents.`,
+        ``,
+        `## All Documentation`,
+    ];
+    // List all docs with brief descriptions
+    for (const doc of docs) {
+        const title = doc.doc.title;
+        const slug = doc.doc.slug;
+        const folder = doc.doc.folder;
+        const desc = extractDescription(doc.html);
+        lines.push(`- [${title}](#/${folder}/${slug}) - ${desc}`);
+    }
+    lines.push("");
+    lines.push("## Endpoints");
+    for (const entry of search) {
+        if (entry.type === "endpoint") {
+            lines.push(`- [${entry.title}](${entry.url}) - ${entry.snippet}`);
+        }
+    }
+    lines.push("");
+    lines.push("## Glossary Terms");
+    for (const entry of search) {
+        if (entry.type === "term") {
+            lines.push(`- [${entry.title}](${entry.url}) - ${entry.snippet}`);
+        }
+    }
+    return lines.join("\n");
+}
+/** Extract a plain-text description from HTML content. */
+function extractDescription(html) {
+    // Strip HTML tags and get first ~200 characters
+    const text = html.replace(/<[^>]+>/g, " ").replace(/\s+/g, " ").trim();
+    return safeSlice(text, 200);
+}
+/**
+ * Slice without splitting a UTF-16 surrogate pair: if `n` lands on a high
+ * surrogate, back off by one so the resulting string is well-formed.
+ */
+function safeSlice(s, n) {
+    if (s.length <= n)
+        return s;
+    let end = n;
+    const code = s.charCodeAt(end - 1);
+    if (code >= 0xd800 && code <= 0xdbff)
+        end -= 1;
+    return s.slice(0, end) + "...";
+}

package/bundle/standalone/node_modules/kxta-publish/dist/render/markdown.d.ts

@@ -0,0 +1,24 @@
+import MarkdownIt from "markdown-it";
+import type { EndpointData, GlossaryTerm } from "../types.js";
+/**
+ * Create a markdown-it instance pre-configured with:
+ * - heading_open rule that injects slugified `id` attributes
+ * - fence rule that routes `mermaid`, `endpoints`, `glossary` fenced
+ *   blocks to their special transformers while leaving ordinary fences
+ *   as normal code blocks.
+ */
+export declare function createMarkdown(): MarkdownIt;
+/**
+ * Convenience wrapper: render markdown body → { html, toc, endpoints }.
+ * Uses a fresh markdown-it instance and collects TOC from heading ids.
+ */
+export declare function renderDocBody(content: string): {
+    html: string;
+    toc: {
+        id: string;
+        text: string;
+        level: number;
+    }[];
+    endpoints: EndpointData[];
+    terms: GlossaryTerm[];
+};

package/bundle/standalone/node_modules/kxta-publish/dist/render/markdown.js

@@ -0,0 +1,87 @@
+import MarkdownIt from "markdown-it";
+import { slugify } from "kxta-core";
+import { renderMermaid } from "./blocks/mermaid.js";
+import { renderEndpoints } from "./blocks/endpoints.js";
+import { renderGlossary } from "./blocks/glossary.js";
+/**
+ * Create a markdown-it instance pre-configured with:
+ * - heading_open rule that injects slugified `id` attributes
+ * - fence rule that routes `mermaid`, `endpoints`, `glossary` fenced
+ *   blocks to their special transformers while leaving ordinary fences
+ *   as normal code blocks.
+ */
+export function createMarkdown() {
+    const md = new MarkdownIt({ html: false, linkify: false, breaks: false });
+    // Inject slugified ids into headings, deduplicated within the document so
+    // repeated headings (e.g. two "## Setup" sections) get distinct anchors.
+    md.core.ruler.push("heading-id", (state) => {
+        const seen = new Set();
+        for (let idx = 0; idx < state.tokens.length; idx++) {
+            const tok = state.tokens[idx];
+            if (tok.type !== "heading_open")
+                continue;
+            const level = Number(tok.tag.replace("h", ""));
+            let text = "";
+            for (let i = idx + 1; i < state.tokens.length; i++) {
+                if (state.tokens[i].type === "heading_close")
+                    break;
+                if (state.tokens[i].content)
+                    text += state.tokens[i].content;
+            }
+            const base = slugify(text).toLowerCase() || `h${level}`;
+            let id = base;
+            let n = 2;
+            while (seen.has(id))
+                id = `${base}-${n++}`;
+            seen.add(id);
+            tok.attrSet("id", id);
+            tok.attrSet("data-heading-level", String(level));
+        }
+        return false;
+    });
+    // Route fenced blocks
+    md.renderer.rules.fence = (tokens, idx, options, env, self) => {
+        const token = tokens[idx];
+        const lang = token.info.trim().split(/\s+/)[0] ?? "";
+        const body = token.content;
+        if (lang === "mermaid")
+            return renderMermaid(body, token.attrGet("id") || "m" + idx);
+        if (lang === "endpoints")
+            return renderEndpoints(body, env.endpoints);
+        if (lang === "glossary")
+            return renderGlossary(body, env);
+        // Default: normal code block
+        const langName = lang || options.langPrefix || "";
+        const code = escapeHtml(body);
+        return `<pre><code class="language-${escapeHtml(langName)}">${code}</code></pre>\n`;
+    };
+    return md;
+}
+/**
+ * Convenience wrapper: render markdown body → { html, toc, endpoints }.
+ * Uses a fresh markdown-it instance and collects TOC from heading ids.
+ */
+export function renderDocBody(content) {
+    const md = createMarkdown();
+    const env = { endpoints: [] };
+    const html = md.render(content, env);
+    // Extract TOC from heading ids in the rendered HTML
+    const toc = [];
+    const headingRe = /<h(\d)[^>]*id="([^"]+)"[^>]*>(.*?)<\/h\d>/g;
+    let m;
+    while ((m = headingRe.exec(html)) !== null) {
+        toc.push({
+            level: Number(m[1]),
+            id: m[2],
+            text: m[3].replace(/<[^>]+>/g, "").trim(),
+        });
+    }
+    return { html, toc, endpoints: env.endpoints, terms: env.terms ?? [] };
+}
+function escapeHtml(str) {
+    return str
+        .replace(/&/g, "&amp;")
+        .replace(/</g, "&lt;")
+        .replace(/>/g, "&gt;")
+        .replace(/"/g, "&quot;");
+}

package/bundle/standalone/node_modules/kxta-publish/dist/render/nav.d.ts

@@ -0,0 +1,21 @@
+import type { NavGroup, RenderedDoc, SearchEntry } from "../types.js";
+/**
+ * Build a navigation tree grouped by folder.
+ *
+ * Within each group items are sorted by:
+ * 1. `frontmatter.order` (ascending, missing → Infinity)
+ * 2. `slug` (ascending)
+ *
+ * The group label can be overridden via `frontmatter.group`.
+ */
+export declare function buildNav(docs: RenderedDoc[]): NavGroup[];
+/**
+ * Build a flat search index from rendered docs.
+ *
+ * Emits entries of type:
+ * - `page` — one per doc (full-page match)
+ * - `heading` — one per TOC entry with hash route
+ * - `endpoint` — one per endpoint with hash route
+ * - `term` — one per glossary term with hash route
+ */
+export declare function buildSearchIndex(docs: RenderedDoc[]): SearchEntry[];

package/bundle/standalone/node_modules/kxta-publish/dist/render/nav.js

@@ -0,0 +1,107 @@
+/** Slice without splitting a UTF-16 surrogate pair. */
+function safeSnippet(s, n) {
+    if (s.length <= n)
+        return s;
+    let end = n;
+    const code = s.charCodeAt(end - 1);
+    if (code >= 0xd800 && code <= 0xdbff)
+        end -= 1;
+    return s.slice(0, end);
+}
+/**
+ * Build a navigation tree grouped by folder.
+ *
+ * Within each group items are sorted by:
+ * 1. `frontmatter.order` (ascending, missing → Infinity)
+ * 2. `slug` (ascending)
+ *
+ * The group label can be overridden via `frontmatter.group`.
+ */
+export function buildNav(docs) {
+    const groups = new Map();
+    for (const r of docs) {
+        const folder = r.doc.folder;
+        if (!groups.has(folder))
+            groups.set(folder, []);
+        groups.get(folder).push(r);
+    }
+    const result = [];
+    for (const [folder, items] of groups) {
+        items.sort((a, b) => {
+            const orderA = a.doc.frontmatter.order ?? Infinity;
+            const orderB = b.doc.frontmatter.order ?? Infinity;
+            if (orderA !== orderB)
+                return orderA - orderB;
+            return a.doc.slug.localeCompare(b.doc.slug);
+        });
+        const groupLabel = items[0]?.doc.frontmatter.group ?? folder;
+        result.push({
+            group: groupLabel,
+            items: items.map((r) => ({
+                title: r.doc.title,
+                slug: r.doc.slug,
+                folder: r.doc.folder,
+                path: r.doc.path,
+            })),
+        });
+    }
+    return result;
+}
+/**
+ * Build a flat search index from rendered docs.
+ *
+ * Emits entries of type:
+ * - `page` — one per doc (full-page match)
+ * - `heading` — one per TOC entry with hash route
+ * - `endpoint` — one per endpoint with hash route
+ * - `term` — one per glossary term with hash route
+ */
+export function buildSearchIndex(docs) {
+    const entries = [];
+    for (const r of docs) {
+        const base = `/${r.doc.folder}/${r.doc.slug}`;
+        // Page entry
+        entries.push({
+            type: "page",
+            title: r.doc.title,
+            folder: r.doc.folder,
+            slug: r.doc.slug,
+            url: `#${base}`,
+            snippet: safeSnippet(r.doc.body, 200),
+        });
+        // Heading entries
+        for (const h of r.toc) {
+            entries.push({
+                type: "heading",
+                title: h.text,
+                folder: r.doc.folder,
+                slug: r.doc.slug,
+                url: `#${base}#${h.id}`,
+                snippet: "",
+            });
+        }
+        // Endpoint entries
+        for (const ep of r.endpoints) {
+            entries.push({
+                type: "endpoint",
+                title: `${ep.method} ${ep.path}`,
+                folder: r.doc.folder,
+                slug: r.doc.slug,
+                url: `#${base}#${ep.id}`,
+                snippet: ep.description ?? "",
+            });
+        }
+        // Glossary term entries
+        for (const term of r.terms ?? []) {
+            entries.push({
+                type: "term",
+                title: term.term,
+                folder: r.doc.folder,
+                slug: r.doc.slug,
+                url: `#${base}#${term.id}`,
+                snippet: term.definition,
+            });
+        }
+    }
+    return entries;
+}

package/bundle/standalone/node_modules/kxta-publish/dist/render/pdf.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Render a markdown file's content to a PDF buffer, on the fly, with no
+ * headless browser. Reuses the same markdown-it pipeline as the static-site
+ * publish feature (renderDocBody), then converts the resulting HTML to a
+ * pdfmake document definition and renders it with pdfmake's bundled Roboto
+ * font (loaded as buffers — see above). Content that requires a real
+ * browser to render (e.g. Mermaid diagrams) is not supported here — it
+ * appears as its raw fenced-code fallback.
+ */
+export declare function renderMarkdownToPdf(content: string): Promise<Buffer>;

package/bundle/standalone/node_modules/kxta-publish/dist/render/pdf.js

@@ -0,0 +1,70 @@
+import pdfMake from "pdfmake";
+import htmlToPdfmake from "html-to-pdfmake";
+import { JSDOM } from "jsdom";
+import { readFileSync } from "node:fs";
+import { createRequire } from "node:module";
+import { dirname, join } from "node:path";
+import { renderDocBody } from "./markdown.js";
+const require = createRequire(import.meta.url);
+// Read pdfmake's own bundled Roboto TTF files as raw buffers, once, at
+// module-load time — in this package's own code, which is never bundled —
+// and register them in pdfmake's virtual filesystem under fixed, arbitrary
+// string keys, instead of using its "standard font by name" shortcut (e.g.
+// `{ Helvetica: { normal: 'Helvetica', ... } }`) or real file paths.
+//
+// That shortcut makes pdfkit resolve font data via a path built from
+// pdfkit's OWN `__dirname` at call time. This module is `require()`d from a
+// Next.js API route; whenever that route ends up bundled (this happened
+// under both webpack and Turbopack despite various externalization
+// attempts — see the design doc for what was tried and rejected), the
+// bundler relocates the code without its co-located *.afm data files, so
+// `__dirname` no longer points anywhere real and pdfkit's file read throws
+// ENOENT.
+//
+// Passing raw Buffers directly as font descriptor values was tried and
+// also rejected: pdfmake's OWN `Printer.resolveUrls` (called before font
+// resolution) treats any object-typed descriptor value as a
+// `{url, headers}` pair — `typeof buffer === 'object'` is true for a
+// Buffer, so it reads `buffer.url` (undefined) and crashes.
+//
+// The virtual filesystem is the mechanism pdfmake actually ships for this:
+// `provideFont` checks `virtualfs.existsSync(key)` BEFORE ever touching the
+// real filesystem or a `__dirname`-relative path, and a plain string key
+// (not starting with a URL scheme or a slash) passes safely through
+// resolveUrls's checks as a no-op ("cannot be resolved" → left alone).
+const robotoFontsDir = dirname(require.resolve("pdfmake/fonts/Roboto/Roboto-Regular.ttf"));
+const ROBOTO_KEYS = {
+    normal: "roboto-normal.ttf",
+    bold: "roboto-bold.ttf",
+    italics: "roboto-italics.ttf",
+    bolditalics: "roboto-bolditalics.ttf",
+};
+pdfMake.virtualfs.writeFileSync(ROBOTO_KEYS.normal, readFileSync(join(robotoFontsDir, "Roboto-Regular.ttf")));
+pdfMake.virtualfs.writeFileSync(ROBOTO_KEYS.bold, readFileSync(join(robotoFontsDir, "Roboto-Medium.ttf")));
+pdfMake.virtualfs.writeFileSync(ROBOTO_KEYS.italics, readFileSync(join(robotoFontsDir, "Roboto-Italic.ttf")));
+pdfMake.virtualfs.writeFileSync(ROBOTO_KEYS.bolditalics, readFileSync(join(robotoFontsDir, "Roboto-MediumItalic.ttf")));
+pdfMake.setFonts({ Roboto: ROBOTO_KEYS });
+// Note: this implementation never wires up `imagesByReference` or any
+// image-fetching option, so there is no code path here that reads a
+// markdown-supplied local path or fetches a markdown-supplied URL — images
+// in source markdown are simply dropped by html-to-pdfmake.
+/**
+ * Render a markdown file's content to a PDF buffer, on the fly, with no
+ * headless browser. Reuses the same markdown-it pipeline as the static-site
+ * publish feature (renderDocBody), then converts the resulting HTML to a
+ * pdfmake document definition and renders it with pdfmake's bundled Roboto
+ * font (loaded as buffers — see above). Content that requires a real
+ * browser to render (e.g. Mermaid diagrams) is not supported here — it
+ * appears as its raw fenced-code fallback.
+ */
+export async function renderMarkdownToPdf(content) {
+    const { html } = renderDocBody(content);
+    const { window } = new JSDOM("");
+    const body = htmlToPdfmake(html, { window });
+    const doc = pdfMake.createPdf({
+        content: body,
+        defaultStyle: { font: "Roboto", fontSize: 11 },
+        pageMargins: [40, 40, 40, 40],
+    });
+    return doc.getBuffer();
+}

package/bundle/standalone/node_modules/kxta-publish/dist/seeds/01-overview.md

@@ -0,0 +1,74 @@
+---
+title: Overview
+group: Getting Started
+order: 1
+icon: 🚀
+---
+
+# kontexta Publish
+
+kontexta Publish is a static documentation site generator that reads markdown files from your kontexta vault and renders them into a beautiful, self-contained single-page application.
+
+## What it does
+
+- **Reads** markdown files from your kontexta vault's knowledge folder
+- **Renders** markdown with support for special blocks (mermaid diagrams, API endpoints, glossary terms)
+- **Generates** a single HTML file with embedded CSS, JavaScript, and data
+- **Provides** a three-pane layout with sidebar navigation, content area, and table of contents
+- **Includes** client-side search, theme toggle, and responsive design
+
+## Quick start
+
+1. Write markdown files in your kontexta vault's knowledge folder
+2. Add frontmatter to control ordering and grouping
+3. Run `kxta-publish` to generate your docs site
+4. Open the generated HTML file in your browser
+
+## Features
+
+### Special Blocks
+
+kontexta Publish supports several special markdown blocks:
+
+- **Mermaid diagrams** — Create flowcharts, sequence diagrams, and more
+- **API endpoints** — Document your API with interactive cards and modal details
+- **Glossary terms** — Build a searchable glossary of terms
+
+### Navigation
+
+- Automatic sidebar navigation grouped by folder
+- Table of contents in the right rail
+- Hash-based routing for deep linking
+- Scroll-spy to highlight current section
+
+### Search
+
+- Client-side search over all document content
+- Search by page title, heading, or content
+- Filter by type (page, heading, endpoint, term)
+
+### Theming
+
+- Dark mode by default
+- Light mode toggle
+- kontexta theme tokens (accent colors, typography, spacing)
+
+## Architecture
+
+```mermaid
+graph LR
+  A[Vault Markdown] --> B[Source Reader]
+  B --> C[Frontmatter Parser]
+  C --> D[Markdown Renderer]
+  D --> E[Nav Builder]
+  D --> F[Search Index Builder]
+  E --> G[Shell Assembler]
+  F --> G
+  G --> H[Single HTML File]
+```
+
+## Next Steps
+
+- Read the [API Documentation](#/getting-started/api) to learn about special blocks
+- Check out the [Glossary](#/getting-started/glossary) for key terms
+- Explore the [Improvements](#/getting-started/improvements) section for future plans