holon-md 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukas Brückner
+
+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

@@ -1,3 +1,176 @@
-# Temporary Holding Version
+# Holon
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Holon compiles a folder of small Markdown files into the documents people read.
+
+## The idea
+
+In a folder of Markdown files, the file you maintain is the file someone reads. The two jobs pull in different directions. Maintaining wants small files that each hold one thing in one place. Reading wants a few complete documents, shaped for whoever opens them.
+
+Holon separates the two. You write a tree of small files. Functions you write project that tree into the documents you publish. Holon runs the functions, fits the heading levels together and keeps every link pointing at the right place.
+
+A product described in three files:
+
+```text
+docs/
+  holon.config.mjs
+  index.md
+  billing.md
+  login.md
+```
+
+`index.md` says where it goes and pulls in its children:
+
+```md
+---
+render_to: README.md
+---
+# Product
+
+## Features
+
+`holon sections()`
+```
+
+`holon.config.mjs` defines what `sections` means:
+
+```js
+export default ({ node, render }) => ({
+  sections: () => node.children.map(render).join("\n\n"),
+});
+```
+
+`billing.md` and `login.md` are plain Markdown, each starting with its own `#` heading. Holon writes one `README.md`:
+
+```md
+# Product
+
+## Features
+
+### Billing
+
+...
+
+### Login
+
+...
+```
+
+An include would paste the two files in as they are. Holon moves their headings to where they now belong and keeps every link pointing where it pointed in the source, so a file reads right wherever it lands: as a section here, as a chapter of another document, or as a file of its own.
+
+The whole [language](#language) fits on one page.
+
+## Language
+
+A source folder is GitHub Flavored Markdown with front matter. Holon gives meaning to four things in it: code that starts with `holon`, the front matter field `render_to`, links, and heading levels. Everything else passes through as written.
+
+### Nodes
+
+Every folder and every `.md` file in the source folder is a node. A folder's `index.md` holds the folder's own text, so from outside a folder looks like a file. Names starting with `.` are skipped, and so are folders without Markdown.
+
+A node is plain data:
+
+| Field | Meaning |
+| :-- | :-- |
+| `path` | Path from the source folder: `/guides/setup.md`, or `/guides` for a folder |
+| `meta` | The front matter |
+| `title` | The text of the first heading as written, or `null` |
+| `children` | The child nodes, sorted by name |
+| `artifact` | The node's own output file from `render_to`, or `null` |
+| `backlinks` | The nodes whose text links to this node |
+| `at(path)` | The node at a path relative to this node's file, or from the source folder with a leading `/` |
+
+Front matter other than `render_to` means nothing to Holon. It is there for your functions to read.
+
+### Calls
+
+Code that starts with the word `holon` is a call. Holon evaluates the rest as a JavaScript expression and puts the resulting string in its place. A code span is a call on one line, a code block tagged `holon` is a call on several:
+
+````md
+See `holon ref("./setup.md")`.
+
+```holon
+node.children
+  .map((child) => `- ${child.title}: ${child.meta.summary}`)
+  .join("\n")
+```
+````
+
+An expression sees `node`, the node whose text contains the call, `render`, and the functions from `holon.config.mjs` in the source folder. That file exports one function. Holon calls it for every call with the same `node` and `render`, so the functions it returns know where they are used:
+
+```js
+export default ({ node, render }) => ({
+  ref: (path) => `[${node.at(path).title}](${node.at(path).path})`,
+});
+```
+
+`render(child)` returns a node's text with its own calls evaluated. Each node renders once. Rendering a node from inside itself is an error.
+
+The text comes between two marker lines. Holon reads them to see where the text ends up and removes them at the end. A function may put a prefix in front of every line, like `> ` or the indent of a list item, but the marker lines must stay whole and on lines of their own. A node without text renders to an empty string without markers.
+
+A call that stands alone in a paragraph, and every `holon` block, may return whole blocks with headings. A call inside text must return a single line. To show a call without running it, put it in a fenced code block, as on this page.
+
+### Files
+
+A node with `render_to` in its front matter becomes a file at that path inside the output folder:
+
+```yaml
+render_to: guides/setup.md
+```
+
+Holon renders these nodes and nothing else. Every other node appears only where a function renders it, which can be several places or none.
+
+### Links
+
+A link points to the same target in the output as in the source. Write it relative to its file, or from the source folder with a leading `/`. A link that a function writes resolves like a link in the node that contains the call.
+
+- A link to a node points to where the node landed. That is its own file if it has `render_to`. Otherwise it is the file its text ended up in, at the node's own first heading. The text must be in exactly one place. Text that a function rendered and then dropped does not count.
+- A link to any other file points to that file in the source folder. Holon copies nothing.
+- A link to a `.md` file that is not a node is an error.
+
+A fragment names one of the target node's own headings, by the anchor the heading has when the node stands alone. A link that is only a fragment, like `#setup`, points to a heading of the node it is written in. Reference links come out as inline links, each with the definition from its own node, and the definitions go.
+
+The links in a node's text are the [backlinks](#nodes) of their targets. Links that only a function writes do not count, because backlinks are read before anything runs.
+
+### Headings
+
+Write every file as if it stood alone, starting at `#`. A heading underlined with `===` or `---` is an error. Holon fits the levels together with one rule: text put into other text starts one level below the last heading that other text wrote above it.
+
+- `render(node)` returns the node with its top headings at level one.
+- A call's result starts one level below the heading above the call.
+- What a function got from `render()` starts one level below the heading the function wrote above it, so a function can group what it renders under headings of its own.
+
+Every heading ends up exactly one level below the heading it belongs to, so gaps close: a file using only `##` and `####` comes out as `#` and `##`. Markdown has six levels. Nesting deeper is an error.
+
+## Essentials
+
+Holon ships no functions. The ones this README is built with are in [holon.config.mjs](docs/holon.config.mjs). Copy what you need:
+
+- `sections()` puts the children one after another, skipping those with their own file.
+- `ref(path)` links to a node with its title as the text.
+- `file(path)` prints the output path of a node with its own file.
+- `backlinks()` lists the nodes that link here.
+- `tree(path)` draws the folder below a path with each node's `summary`.
+
+## Usage
+
+```sh
+npm install --save-dev holon-md
+npx holon-md docs .
+```
+
+The first argument is the source folder, the second the output folder. Every file lands inside the output folder and none inside the source folder. Holon prints every file as it writes it and stops at the first error, saying where it happened.
+
+This README is compiled from:
+
+```yaml
+/:
+  1-idea.md: # Why the files you write and the files you read should differ.
+  2-language: # Nodes, calls, files, links and headings.
+    1-nodes.md: # What functions see.
+    2-calls.md: # Code that runs.
+    3-files.md: # Which nodes become files.
+    4-links.md: # Where links point after compiling.
+    5-headings.md: # How heading levels fit together.
+  3-essentials.md: # Functions worth copying.
+  4-usage.md: # Install and run.
+```

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
+    if (typeof path === "string" && /^\.\.?\//.test(path)) {
+        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
+            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
+        });
+    }
+    return path;
+};
+import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { pathToFileURL } from "node:url";
+import { compile } from "./compile.js";
+import { message } from "./tree.js";
+const args = process.argv.slice(2);
+if (args.length !== 2) {
+    console.error("usage: holon <source folder> <output folder>");
+    process.exit(1);
+}
+const [source, output] = args;
+try {
+    for (const artifact of compile(source, output, await loadConfig(source))) {
+        const file = join(output, artifact.path);
+        mkdirSync(dirname(file), { recursive: true });
+        writeFileSync(file, artifact.content);
+        console.log(artifact.path);
+    }
+}
+catch (error) {
+    console.error(`holon: ${message(error)}`);
+    process.exit(1);
+}
+/** The default export of `holon.config.mjs` in `sourceDir`, or undefined without one. */
+async function loadConfig(sourceDir) {
+    const file = resolve(sourceDir, "holon.config.mjs");
+    if (!existsSync(file))
+        return undefined;
+    let module;
+    try {
+        module = await import(__rewriteRelativeImportExtension(pathToFileURL(file).href));
+    }
+    catch (error) {
+        throw new Error(`holon.config.mjs: ${message(error)}`);
+    }
+    if (typeof module.default !== "function")
+        throw new Error("holon.config.mjs must export a default function");
+    return module.default;
+}

package/dist/compile.d.ts

@@ -0,0 +1,8 @@
+import { type Config } from "./render.ts";
+/** A file to write: its path inside the output folder and its content. */
+export type Artifact = {
+    path: string;
+    content: string;
+};
+/** Compile `sourceDir` for `outputDir` without writing anything. */
+export declare function compile(sourceDir: string, outputDir: string, config?: Config): Artifact[];

package/dist/compile.js

@@ -0,0 +1,120 @@
+import { dirname, isAbsolute, join, posix, relative, resolve, sep } from "node:path";
+import { anchors, applyEdits, destinations, formatUrl, headings, parse, start } from "./markdown.js";
+import { contains, createRender } from "./render.js";
+import { loadTree, message, preorder, resolveLink } from "./tree.js";
+/** Compile `sourceDir` for `outputDir` without writing anything. */
+export function compile(sourceDir, outputDir, config) {
+    const source = resolve(sourceDir);
+    const output = resolve(outputDir);
+    const tree = loadTree(source);
+    const { render, markers } = createRender(tree, config ?? null);
+    const files = new Map();
+    for (const node of preorder(tree.root)) {
+        if (!node.artifact)
+            continue;
+        const other = files.get(node.artifact);
+        if (other)
+            throw new Error(`${other.path} and ${node.path} both render_to ${node.artifact}`);
+        const target = resolve(output, node.artifact);
+        if (!within(output, target))
+            throw new Error(`${node.path} would render_to ${node.artifact}, which is not inside the output folder`);
+        if (within(source, target))
+            throw new Error(`${node.path} would render_to ${node.artifact}, which is inside the source folder`);
+        files.set(node.artifact, node);
+    }
+    if (files.size === 0)
+        throw new Error("no node has render_to, so there is nothing to write");
+    const texts = new Map();
+    for (const [path, node] of files)
+        texts.set(path, render(node));
+    // Read from the markers where each node's text ended up and which headings are its own.
+    const places = new Map();
+    const marked = new Map();
+    for (const [file, text] of texts) {
+        const list = headings(parse(text));
+        const names = anchors(list);
+        let found;
+        try {
+            found = markers(text);
+        }
+        catch (error) {
+            throw new Error(`${file}: ${message(error)}`);
+        }
+        const owners = list.map((heading) => innermost(found.regions, start(heading)));
+        for (const region of found.regions) {
+            const own = owners.flatMap((owner, i) => (owner === region ? [i] : []));
+            const alone = anchors(own.map((i) => list[i]));
+            const place = { file, anchors: new Map(alone.map((anchor, j) => [anchor, names[own[j]]])) };
+            places.set(region.path, [...(places.get(region.path) ?? []), place]);
+        }
+        marked.set(file, found);
+    }
+    /** The file a node's text is in, and the anchors of its headings there. */
+    const landing = (node) => {
+        const found = places.get(node.path) ?? [];
+        if (node.artifact)
+            return found.find((place) => place.file === node.artifact) ?? { file: node.artifact, anchors: new Map() };
+        if (found.length === 1)
+            return found[0];
+        const where = found.length === 0 ? "no file" : `${found.length} places (${[...new Set(found.map((place) => place.file))].join(", ")})`;
+        throw new Error(`${node.path} has no render_to and its text is in ${where}, so links to it have no target`);
+    };
+    /** Where a link from `from` to `node` points. */
+    const nodeUrl = (node, fragment, from) => {
+        const place = landing(node);
+        let anchor = null;
+        if (fragment !== null) {
+            anchor = place.anchors.get(fragment) ?? null;
+            if (anchor === null)
+                throw new Error(`${node.path} has no heading with the anchor #${fragment}`);
+        }
+        else if (!node.artifact) {
+            anchor = place.anchors.values().next().value ?? null;
+            if (anchor === null)
+                throw new Error(`${node.path} has no heading in ${place.file} to link to`);
+        }
+        const path = place.file === from ? (anchor === null ? posix.basename(place.file) : "") : posix.relative(posix.dirname(from), place.file);
+        return formatUrl(path, anchor);
+    };
+    /** Where a link to a file that is not a node points: the file in the source folder. */
+    const fileUrl = (path, fragment, from) => {
+        const target = join(source, ...path.split("/"));
+        return formatUrl(relative(dirname(join(output, from)), target).split(sep).join("/"), fragment);
+    };
+    return [...texts].map(([path, text]) => {
+        const { regions, removals } = marked.get(path);
+        const edits = [...removals];
+        // Every link Holon handles is an absolute source path by now, see render().
+        for (const found of destinations(text, parse(text))) {
+            const target = resolveLink(tree, found.url, tree.sources.get(files.get(path)), path);
+            if (!target)
+                continue;
+            let url;
+            try {
+                url = target.node ? nodeUrl(target.node, target.fragment, path) : fileUrl(target.path, target.fragment, path);
+            }
+            catch (error) {
+                const owner = innermost(regions, found.start).path;
+                const file = tree.sources.get(tree.nodes.get(owner))?.file ?? owner;
+                throw new Error(`${path}: link in ${file}: ${message(error)}`);
+            }
+            edits.push({ start: found.start, end: found.end, text: url });
+        }
+        // Removing the last marker line leaves the line break before it behind.
+        return { path, content: `${applyEdits(text, edits).replace(/\n+$/, "")}\n` };
+    });
+}
+/** Whether `path` lies inside `folder`, the folder itself excluded. */
+function within(folder, path) {
+    const inside = relative(folder, path);
+    return inside !== "" && inside !== ".." && !inside.startsWith(`..${sep}`) && !isAbsolute(inside);
+}
+/** The innermost region around `offset`. */
+function innermost(regions, offset) {
+    let found;
+    for (const region of regions) {
+        if (contains(region, offset) && (!found || region.start > found.start))
+            found = region;
+    }
+    return found;
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { compile, type Artifact } from "./compile.ts";
+export type { Config, Context } from "./render.ts";
+export type { Node } from "./tree.ts";

package/dist/index.js

@@ -0,0 +1 @@
+export { compile } from "./compile.js";

package/dist/markdown.d.ts

@@ -0,0 +1,38 @@
+import type { Heading, Nodes, Root } from "mdast";
+/** Replace `text.slice(start, end)` with `text`. */
+export type Edit = {
+    start: number;
+    end: number;
+    text: string;
+};
+/** Where a link, image or definition points, and the span of its destination in the text. */
+export type Destination = {
+    url: string;
+    start: number;
+    end: number;
+};
+export declare function parse(text: string): Root;
+export declare function walk(node: Nodes, visit: (node: Nodes, ancestors: Nodes[]) => void, ancestors?: Nodes[]): void;
+export declare function start(node: Nodes): number;
+export declare function end(node: Nodes): number;
+export declare function applyEdits(text: string, edits: Edit[]): string;
+export declare function headings(root: Root): Heading[];
+export declare function plainText(node: Nodes): string;
+/** The anchor GitHub derives from a heading's text. */
+export declare function slug(text: string): string;
+/** The anchors of all headings in order, with GitHub's `-1`, `-2` suffixes for repeats. */
+export declare function anchors(list: Heading[]): string[];
+/**
+ * The level of each heading such that it sits exactly one level below the
+ * heading it belongs to, with the top level at `base`.
+ */
+export declare function levels(list: Heading[], base: number): number[];
+/** The change that moves `heading` to level `depth`, or null if it is there already. A heading with `#` stands on one line. */
+export declare function levelEdit(heading: Heading, depth: number): Edit | null;
+/** The change that removes the lines from the one holding `from` to the one holding `to`. A block between blank lines takes one of them along. */
+export declare function removeLines(text: string, from: number, to: number): Edit;
+export declare function destinations(text: string, root: Root): Destination[];
+/** The changes that turn reference links and images into inline ones, each with the destination and title of the definition it uses, and remove the definitions. */
+export declare function referenceEdits(text: string, root: Root): Edit[];
+/** A link destination: the path with every segment percent-encoded, then the fragment. */
+export declare function formatUrl(path: string, fragment: string | null): string;

package/dist/markdown.js

@@ -0,0 +1,171 @@
+import { fromMarkdown } from "mdast-util-from-markdown";
+import { gfmFromMarkdown } from "mdast-util-gfm";
+import { parse as tokenize, postprocess, preprocess } from "micromark";
+import { gfm } from "micromark-extension-gfm";
+/** Holon reads GitHub Flavored Markdown, the dialect whose anchors it writes. */
+const extensions = [gfm()];
+export function parse(text) {
+    return fromMarkdown(text, { extensions, mdastExtensions: [gfmFromMarkdown()] });
+}
+export function walk(node, visit, ancestors = []) {
+    visit(node, ancestors);
+    if ("children" in node) {
+        for (const child of node.children)
+            walk(child, visit, [...ancestors, node]);
+    }
+}
+export function start(node) {
+    return node.position.start.offset;
+}
+export function end(node) {
+    return node.position.end.offset;
+}
+export function applyEdits(text, edits) {
+    let result = "";
+    let at = 0;
+    for (const edit of [...edits].sort((a, b) => a.start - b.start)) {
+        if (edit.start < at)
+            throw new Error("two changes overlap");
+        result += text.slice(at, edit.start) + edit.text;
+        at = edit.end;
+    }
+    return result + text.slice(at);
+}
+export function headings(root) {
+    const found = [];
+    walk(root, (node) => {
+        if (node.type === "heading")
+            found.push(node);
+    });
+    return found;
+}
+export function plainText(node) {
+    if (node.type === "text" || node.type === "inlineCode")
+        return node.value;
+    if ("children" in node)
+        return node.children.map(plainText).join("");
+    return "";
+}
+/** The anchor GitHub derives from a heading's text. */
+export function slug(text) {
+    return text
+        .toLowerCase()
+        .replace(/[^\p{L}\p{M}\p{N}\p{Pc} -]/gu, "")
+        .replace(/ /g, "-");
+}
+/** The anchors of all headings in order, with GitHub's `-1`, `-2` suffixes for repeats. */
+export function anchors(list) {
+    const used = new Map();
+    const result = [];
+    for (const heading of list) {
+        const base = slug(plainText(heading));
+        let anchor = base;
+        while (used.has(anchor)) {
+            const count = used.get(base) + 1;
+            used.set(base, count);
+            anchor = `${base}-${count}`;
+        }
+        used.set(anchor, 0);
+        result.push(anchor);
+    }
+    return result;
+}
+/**
+ * The level of each heading such that it sits exactly one level below the
+ * heading it belongs to, with the top level at `base`.
+ */
+export function levels(list, base) {
+    const open = [];
+    return list.map((heading) => {
+        while (open.length > 0 && open[open.length - 1] >= heading.depth)
+            open.pop();
+        open.push(heading.depth);
+        const depth = base + open.length - 1;
+        if (depth > 6)
+            throw new Error(`heading "${plainText(heading)}" would need level ${depth}, Markdown stops at 6`);
+        return depth;
+    });
+}
+/** The change that moves `heading` to level `depth`, or null if it is there already. A heading with `#` stands on one line. */
+export function levelEdit(heading, depth) {
+    const { start: from, end: to } = heading.position;
+    if (from.line !== to.line)
+        throw new Error(`heading "${plainText(heading)}" is underlined with === or ---, write it with #`);
+    if (heading.depth === depth)
+        return null;
+    return { start: from.offset, end: from.offset + heading.depth, text: "#".repeat(depth) };
+}
+/** The change that removes the lines from the one holding `from` to the one holding `to`. A block between blank lines takes one of them along. */
+export function removeLines(text, from, to) {
+    const start = text.lastIndexOf("\n", from - 1) + 1;
+    const lineEnd = text.indexOf("\n", to);
+    const end = lineEnd < 0 ? text.length : lineEnd + 1;
+    return { start, end: text.endsWith("\n\n", start) && text.startsWith("\n", end) ? end + 1 : end, text: "" };
+}
+/** The syntax of every link, image and definition in `text`, by the node's start. */
+function syntax(text) {
+    const found = new Map();
+    const open = [];
+    for (const [kind, token] of postprocess(tokenize({ extensions }).document().write(preprocess()(text, "utf8", true)))) {
+        const span = { start: token.start.offset, end: token.end.offset };
+        if (token.type === "link" || token.type === "image" || token.type === "definition") {
+            if (kind === "exit") {
+                open.pop();
+            }
+            else {
+                const current = { end: span.end, label: span.start, destination: null, title: null };
+                found.set(span.start, current);
+                open.push(current);
+            }
+        }
+        else if (kind === "exit" && open.length > 0) {
+            const current = open[open.length - 1];
+            if (token.type === "label")
+                current.label = span.end;
+            else if (token.type === "resourceDestination" || token.type === "definitionDestination")
+                current.destination = span;
+            else if (token.type === "resourceTitle" || token.type === "definitionTitle")
+                current.title = span;
+        }
+    }
+    return found;
+}
+export function destinations(text, root) {
+    const spans = syntax(text);
+    const found = [];
+    walk(root, (node) => {
+        if (node.type !== "link" && node.type !== "image" && node.type !== "definition")
+            return;
+        const destination = spans.get(start(node))?.destination;
+        if (destination)
+            found.push({ url: node.url, ...destination });
+    });
+    return found;
+}
+/** The changes that turn reference links and images into inline ones, each with the destination and title of the definition it uses, and remove the definitions. */
+export function referenceEdits(text, root) {
+    const spans = syntax(text);
+    const definitions = new Map();
+    const references = [];
+    const edits = [];
+    walk(root, (node) => {
+        if (node.type === "definition") {
+            if (!definitions.has(node.identifier))
+                definitions.set(node.identifier, spans.get(start(node)));
+            edits.push(removeLines(text, start(node), end(node)));
+        }
+        else if (node.type === "linkReference" || node.type === "imageReference")
+            references.push(node);
+    });
+    for (const node of references) {
+        const reference = spans.get(start(node));
+        const { destination, title } = definitions.get(node.identifier);
+        edits.push({ start: reference.label, end: reference.end, text: `(${text.slice(destination.start, (title ?? destination).end)})` });
+    }
+    return edits;
+}
+/** A link destination: the path with every segment percent-encoded, then the fragment. */
+export function formatUrl(path, fragment) {
+    const encoded = path.split("/").map(encodeURIComponent).join("/");
+    return fragment === null ? encoded : `${encoded}#${fragment}`;
+}

package/dist/render.d.ts

@@ -0,0 +1,30 @@
+import { type Edit } from "./markdown.ts";
+import { type Node, type Tree } from "./tree.ts";
+/** The default export of `holon.config.mjs`: called for every holon call with the node that contains it. */
+export type Config = (context: Context) => Record<string, (...args: any[]) => unknown>;
+export type Context = {
+    node: Node;
+    render: (node: Node) => string;
+};
+/** The span of a text between the markers `render()` put around a node. */
+export type Region = {
+    path: string;
+    start: number;
+    end: number;
+};
+/**
+ * `render(node)` returns a node's text with its calls evaluated, its links
+ * pointing at source paths and its top headings at level 1, between two
+ * marker lines that tell Holon where the text ends up. `markers(text)` reads
+ * those lines back. Markers carry an id that is new for every compile, so no
+ * source text can contain one.
+ */
+export declare function createRender(tree: Tree, config: Config | null): {
+    render: (node: Node) => string;
+    markers: (text: string) => {
+        regions: Region[];
+        removals: Edit[];
+    };
+};
+/** Whether `offset` lies in `region`. */
+export declare function contains(region: Region, offset: number): boolean;

package/dist/render.js

@@ -0,0 +1,224 @@
+import { randomUUID } from "node:crypto";
+import { applyEdits, destinations, end, formatUrl, headings, levelEdit, levels, parse, referenceEdits, removeLines, start, walk, } from "./markdown.js";
+import { location, message, resolveLink } from "./tree.js";
+/**
+ * `render(node)` returns a node's text with its calls evaluated, its links
+ * pointing at source paths and its top headings at level 1, between two
+ * marker lines that tell Holon where the text ends up. `markers(text)` reads
+ * those lines back. Markers carry an id that is new for every compile, so no
+ * source text can contain one.
+ */
+export function createRender(tree, config) {
+    const done = new Map();
+    const active = [];
+    const id = randomUUID().slice(0, 8);
+    function render(node) {
+        const source = tree.sources.get(node);
+        if (!source)
+            throw new Error(`render() expects a node, got ${describe(node)}`);
+        const cached = done.get(node);
+        if (cached !== undefined)
+            return cached;
+        if (active.includes(node)) {
+            const cycle = [...active.slice(active.indexOf(node)), node].map((n) => n.path);
+            throw new Error(`render cycle: ${cycle.join(" -> ")}`);
+        }
+        active.push(node);
+        try {
+            const text = renderSource(source);
+            done.set(node, text);
+            return text;
+        }
+        finally {
+            active.pop();
+        }
+    }
+    function renderSource(source) {
+        const list = headings(source.root);
+        const depths = levels(list, 1);
+        let edits;
+        try {
+            edits = list.flatMap((heading, i) => levelEdit(heading, depths[i]) ?? []);
+        }
+        catch (error) {
+            throw new Error(`${source.file}: ${message(error)}`);
+        }
+        edits.push(...referenceEdits(source.body, source.root));
+        for (const call of findCalls(source, list, depths)) {
+            const text = expand(call, source);
+            // An empty result leaves no block behind.
+            edits.push(call.block && text === "" ? removeLines(source.body, call.start, call.end) : { start: call.start, end: call.end, text });
+        }
+        return mark(source.node, linkToSources(applyEdits(source.body, edits), source));
+    }
+    function expand(call, source) {
+        try {
+            const text = evaluate(call.expression, source.node);
+            if (!call.block) {
+                if (/[\r\n]/.test(text))
+                    throw new Error("a call inside text must return a single line");
+                return text;
+            }
+            return place(text, call.level + 1);
+        }
+        catch (error) {
+            throw new Error(`${call.where}: ${message(error)}`);
+        }
+    }
+    /**
+     * Fit the headings of a call's result in. Those the function wrote itself
+     * start at `base`. Each text it got from render() starts one level below the
+     * last heading the function wrote above it.
+     */
+    function place(text, base) {
+        const list = headings(parse(text));
+        const all = markers(text).regions;
+        const outer = all.filter((region) => !all.some((other) => other !== region && other.start <= region.start && region.end <= other.end));
+        const own = list.filter((heading) => !outer.some((region) => contains(region, start(heading))));
+        const depths = levels(own, base);
+        const edits = own.flatMap((heading, i) => levelEdit(heading, depths[i]) ?? []);
+        for (const region of outer) {
+            const inside = list.filter((heading) => contains(region, start(heading)));
+            const fitted = levels(inside, levelBefore(own, depths, region.start, base - 1) + 1);
+            edits.push(...inside.flatMap((heading, i) => levelEdit(heading, fitted[i]) ?? []));
+        }
+        return applyEdits(text, edits);
+    }
+    function evaluate(expression, node) {
+        const functions = config ? config({ node, render }) : {};
+        if (typeof functions !== "object" || functions === null)
+            throw new Error("holon.config.mjs must return an object of functions");
+        for (const name of Object.keys(functions)) {
+            if (name === "node" || name === "render")
+                throw new Error(`holon.config.mjs: "${name}" is taken`);
+            if (!usable(name))
+                throw new Error(`holon.config.mjs: "${name}" cannot be the name of a function`);
+        }
+        const scope = { ...functions, node, render };
+        const run = new Function(...Object.keys(scope), `"use strict";\nreturn (\n${expression}\n);`);
+        const value = run(...Object.values(scope));
+        if (typeof value !== "string")
+            throw new Error(`a call must produce a string, got ${describe(value)}`);
+        return value;
+    }
+    /** Rewrite links to absolute source paths, so they keep their meaning wherever the text lands. */
+    function linkToSources(text, source) {
+        const where = source.file ?? source.node.path;
+        const edits = [];
+        for (const found of destinations(text, parse(text))) {
+            const target = resolveLink(tree, found.url, source, where);
+            if (target)
+                edits.push({ start: found.start, end: found.end, text: formatUrl(target.path, target.fragment) });
+        }
+        return applyEdits(text, edits);
+    }
+    /** Wrap a node's text in marker lines. They stand on lines of their own, so blank lines around the text go. Empty text gets no markers. */
+    function mark(node, text) {
+        const body = text.replace(/^(?:[ \t]*\n)+/, "").trimEnd();
+        if (body === "")
+            return "";
+        const path = encodeURI(node.path);
+        return `<!-- holon ${id} start ${path} -->\n${body}\n<!-- holon ${id} end ${path} -->`;
+    }
+    /**
+     * The regions the marker lines in `text` enclose, and the changes that remove
+     * those lines. A marker line may carry a prefix that a function added to every
+     * line, like `> ` or spaces, but nothing else.
+     */
+    function markers(text) {
+        const regions = [];
+        const removals = [];
+        const open = [];
+        for (const found of text.matchAll(new RegExp(`<!-- holon ${id} (start|end) (\\S+) -->`, "g"))) {
+            const path = decodeURI(found[2]);
+            const removal = removeLines(text, found.index, found.index + found[0].length);
+            const before = text.slice(removal.start, found.index);
+            const after = text.slice(found.index + found[0].length, removal.end);
+            if (!/^[ \t>]*$/.test(before) || !/^[ \t]*\n?$/.test(after)) {
+                throw new Error(`a function wrote text next to a marker line of ${path}; the text render() returns must stay on lines of its own`);
+            }
+            removals.push(removal);
+            if (found[1] === "start") {
+                open.push({ path, start: removal.end });
+                continue;
+            }
+            const index = open.map((region) => region.path).lastIndexOf(path);
+            if (index < 0)
+                throw cutApart(path);
+            if (index < open.length - 1)
+                throw cutApart(open[open.length - 1].path);
+            regions.push({ path, start: open.pop().start, end: removal.start });
+        }
+        if (open.length > 0)
+            throw cutApart(open[open.length - 1].path);
+        return { regions, removals };
+    }
+    return { render, markers };
+}
+function cutApart(path) {
+    return new Error(`a function cut the rendered text of ${path} apart; keep the marker lines render() puts around it`);
+}
+/** Whether `offset` lies in `region`. */
+export function contains(region, offset) {
+    return region.start <= offset && offset < region.end;
+}
+/** The level of the last heading in `list` before `offset`, or `none` if there is no heading before it. */
+function levelBefore(list, depths, offset, none) {
+    let level = none;
+    for (let i = 0; i < list.length && start(list[i]) < offset; i++)
+        level = depths[i];
+    return level;
+}
+/** Whether a call can use `name`: JavaScript accepts it as the name of a function. */
+function usable(name) {
+    try {
+        new Function(`"use strict"; function ${name}() {}`);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function findCalls(source, list, depths) {
+    const calls = [];
+    walk(source.root, (node, ancestors) => {
+        const expression = holonExpression(node, source);
+        if (expression === null)
+            return;
+        const parent = ancestors[ancestors.length - 1];
+        const where = location(source, start(node));
+        let block;
+        if (node.type === "code") {
+            if (parent?.type !== "root")
+                throw new Error(`${where}: a holon block must stand at the top level, not inside a ${parent?.type}`);
+            block = true;
+        }
+        else {
+            block = parent?.type === "paragraph" && parent.children.length === 1 && ancestors[ancestors.length - 2]?.type === "root";
+        }
+        // The call sits below the last heading before it, at that heading's level in the finished text.
+        const level = levelBefore(list, depths, start(node), 0);
+        calls.push({ expression, start: start(node), end: end(node), block, level, where });
+    });
+    return calls;
+}
+/** The expression of a holon call, or null if the node is not one. */
+function holonExpression(node, source) {
+    if (node.type === "code" && node.lang === "holon") {
+        if (node.meta)
+            throw new Error(`${location(source, start(node))}: unexpected "${node.meta}" after holon`);
+        return node.value;
+    }
+    if (node.type === "inlineCode") {
+        const match = /^holon\s+(\S[\s\S]*)$/.exec(node.value);
+        return match ? match[1] : null;
+    }
+    return null;
+}
+function describe(value) {
+    if (typeof value === "function")
+        return "a function (call it to get its text)";
+    if (value === null || value === undefined)
+        return String(value);
+    return typeof value === "object" ? "an object" : `the ${typeof value} ${String(value)}`;
+}

package/dist/tree.d.ts

@@ -0,0 +1,48 @@
+import type { Root } from "mdast";
+/** A folder or a Markdown file, as functions see it. */
+export type Node = {
+    /** Path from the source folder: `/` for the root, `/guides` for a folder, `/guides/setup.md` for a file. */
+    path: string;
+    /** The front matter. */
+    meta: Record<string, unknown>;
+    /** Text of the first heading as written, or null. */
+    title: string | null;
+    /** Output path from `render_to`, or null. */
+    artifact: string | null;
+    children: readonly Node[];
+    /** Nodes whose text links to this node. */
+    backlinks: readonly Node[];
+    /** The node at `path`, relative to this node's folder or, with a leading `/`, to the source folder. */
+    at(path: string): Node;
+};
+/** What Holon keeps about a node besides what functions see. */
+export type Source = {
+    node: Node;
+    /** The file holding the node's text, for messages. Null for a folder without index.md. */
+    file: string | null;
+    /** The folder that relative paths in the text start from. */
+    dir: string;
+    /** The text after the front matter. */
+    body: string;
+    root: Root;
+    /** Line of the file on which `body` starts. */
+    line: number;
+};
+export type Tree = {
+    dir: string;
+    root: Node;
+    nodes: Map<string, Node>;
+    sources: Map<Node, Source>;
+};
+/** A link target in source terms, or null for links Holon leaves alone. */
+export type Target = {
+    path: string;
+    fragment: string | null;
+    node: Node | null;
+};
+export declare function loadTree(dir: string): Tree;
+export declare function preorder(node: Node): Node[];
+export declare function location(source: Source, offset: number): string;
+/** The target of `url` in `source`'s text, or null for links Holon leaves alone. */
+export declare function resolveLink(tree: Tree, url: string, source: Source, where: string): Target | null;
+export declare function message(error: unknown): string;

package/dist/tree.js

@@ -0,0 +1,150 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join, posix } from "node:path";
+import { parse as parseYaml } from "yaml";
+import { destinations, headings, parse, plainText } from "./markdown.js";
+export function loadTree(dir) {
+    const tree = { dir, root: undefined, nodes: new Map(), sources: new Map() };
+    tree.root = loadFolder(tree, "/") ?? loadNode(tree, "/", null, "/", []);
+    for (const node of preorder(tree.root)) {
+        const source = tree.sources.get(node);
+        for (const { url, start } of destinations(source.body, source.root)) {
+            const target = resolveLink(tree, url, source, location(source, start))?.node;
+            if (target && target !== node && !target.backlinks.includes(node))
+                target.backlinks.push(node);
+        }
+    }
+    // Functions share these nodes, so nobody may change them.
+    for (const node of tree.nodes.values()) {
+        freeze(node.meta);
+        Object.freeze(node.children);
+        Object.freeze(node.backlinks);
+        Object.freeze(node);
+    }
+    return tree;
+}
+/** Freeze `value` and everything in it. */
+function freeze(value) {
+    if (Object.isFrozen(value))
+        return;
+    Object.freeze(value);
+    for (const inner of Object.values(value))
+        freeze(inner);
+}
+export function preorder(node) {
+    return [node, ...node.children.flatMap(preorder)];
+}
+export function location(source, offset) {
+    const line = source.line + source.body.slice(0, offset).split("\n").length - 1;
+    return `${source.file ?? source.node.path}:${line}`;
+}
+/** Resolve `target` against folder `dir`. Paths leaving the source folder keep their leading `..` segments. */
+function resolvePath(dir, target) {
+    const parts = target.startsWith("/") ? [] : dir.split("/").filter(Boolean);
+    for (const segment of target.split("/")) {
+        if (segment === "" || segment === ".")
+            continue;
+        if (segment === ".." && parts.length > 0 && parts[parts.length - 1] !== "..")
+            parts.pop();
+        else
+            parts.push(segment);
+    }
+    return `/${parts.join("/")}`;
+}
+function lookup(tree, path) {
+    return tree.nodes.get(path.endsWith("/index.md") ? path.slice(0, -"/index.md".length) || "/" : path);
+}
+/** The target of `url` in `source`'s text, or null for links Holon leaves alone. */
+export function resolveLink(tree, url, source, where) {
+    if (url === "" || /^(\?|\/\/|[a-z][a-z0-9+.-]*:)/i.test(url))
+        return null;
+    const hash = url.indexOf("#");
+    const path = hash === 0 ? source.node.path : resolvePath(source.dir, decode(hash < 0 ? url : url.slice(0, hash)));
+    const fragment = hash < 0 || hash === url.length - 1 ? null : url.slice(hash + 1);
+    const node = lookup(tree, path) ?? null;
+    if (!node && path.endsWith(".md") && !path.startsWith("/..")) {
+        throw new Error(`${where}: link to ${path}, which is not a Markdown file in the source folder`);
+    }
+    return { path, fragment, node };
+}
+export function message(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function decode(path) {
+    try {
+        return decodeURIComponent(path);
+    }
+    catch {
+        return path;
+    }
+}
+function loadFolder(tree, path) {
+    const entries = readdirSync(join(tree.dir, path), { withFileTypes: true })
+        .filter((entry) => !entry.name.startsWith("."))
+        .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+    const children = [];
+    let index = null;
+    for (const entry of entries) {
+        const childPath = path === "/" ? `/${entry.name}` : `${path}/${entry.name}`;
+        if (entry.isDirectory()) {
+            const child = loadFolder(tree, childPath);
+            if (child)
+                children.push(child);
+        }
+        else if (entry.name === "index.md") {
+            index = childPath;
+        }
+        else if (entry.name.endsWith(".md")) {
+            children.push(loadNode(tree, childPath, childPath, path, []));
+        }
+    }
+    if (!index && children.length === 0)
+        return null;
+    return loadNode(tree, path, index, path, children);
+}
+function loadNode(tree, path, file, dir, children) {
+    const text = file ? readFileSync(join(tree.dir, file), "utf8").replace(/^/, "").replace(/\r\n?/g, "\n") : "";
+    const { meta, body, line } = splitFrontMatter(text, file);
+    const root = parse(body);
+    const first = headings(root)[0];
+    const node = {
+        path,
+        meta,
+        title: first ? plainText(first).trim() : null,
+        artifact: renderTo(meta, file),
+        children,
+        backlinks: [],
+        at: (target) => {
+            const found = lookup(tree, resolvePath(dir, target));
+            if (!found)
+                throw new Error(`${path}: at("${target}") matches no Markdown file or folder`);
+            return found;
+        },
+    };
+    tree.nodes.set(path, node);
+    tree.sources.set(node, { node, file, dir, body, root, line });
+    return node;
+}
+function splitFrontMatter(text, file) {
+    const match = /^---[ \t]*\n(?:([\s\S]*?)\n)?---[ \t]*(?:\n|$)/.exec(text);
+    if (!match)
+        return { meta: {}, body: text, line: 1 };
+    let meta;
+    try {
+        meta = parseYaml(match[1] ?? "") ?? {};
+    }
+    catch (error) {
+        throw new Error(`${file}: front matter is not valid YAML: ${message(error)}`);
+    }
+    if (typeof meta !== "object" || Array.isArray(meta))
+        throw new Error(`${file}: front matter must be a mapping`);
+    return { meta: meta, body: text.slice(match[0].length), line: match[0].split("\n").length };
+}
+function renderTo(meta, file) {
+    const value = meta.render_to;
+    if (value === undefined)
+        return null;
+    if (typeof value !== "string" || value.includes("\\") || value.endsWith("/")) {
+        throw new Error(`${file}: render_to must be a file path with forward slashes, like guides/setup.md`);
+    }
+    return posix.normalize(value);
+}

package/package.json

@@ -1,6 +1,57 @@
 {
   "name": "holon-md",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "Compile a folder of small Markdown files into the documents people read.",
+  "keywords": [
+    "markdown",
+    "documentation",
+    "docs-as-code",
+    "readme",
+    "include",
+    "transclusion",
+    "single-source",
+    "compiler",
+    "cli"
+  ],
+  "license": "MIT",
+  "author": "Lukas Brückner",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/LukasB97/holon.git"
+  },
+  "homepage": "https://github.com/LukasB97/holon#readme",
+  "bugs": "https://github.com/LukasB97/holon/issues",
+  "type": "module",
+  "bin": {
+    "holon": "dist/cli.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22.18"
+  },
+  "dependencies": {
+    "mdast-util-from-markdown": "^2.1.0",
+    "mdast-util-gfm": "^3.1.0",
+    "micromark": "^4.0.3",
+    "micromark-extension-gfm": "^3.0.0",
+    "yaml": "^2.9.1"
+  },
+  "devDependencies": {
+    "@types/mdast": "^4.0.4",
+    "@types/node": "^22.20.5",
+    "typescript": "^7.0.2"
+  },
+  "scripts": {
+    "build": "tsc",
+    "test": "node --test test/holon.test.ts",
+    "docs": "node src/cli.ts docs ."
+  }
 }