typescript-mdma

typescript-mdma¶

Render one or more Markdown strings from an .mdma template and a typed inputs object.

This is the TypeScript reference implementation of MDMA. See the language specification and docs for the full grammar, filter reference, and worked examples.

Install¶

npm install typescript-mdma

Usage¶

import { render } from "typescript-mdma";
import { readFileSync } from "node:fs";

const source = readFileSync("release-notes.mdma", "utf-8");
const result = render(source, {
  project: "Acme SDK",
  version: "3.0.0",
  date: "2026-07-01",
  added: ["WebSocket support"],
  breaking: true,
  releases: [{ version: "2.1.0", date: "2026-06-01", added: ["Dark mode"] }],
});

result.slug;             // "Acme SDK-3.0.0"          (string)
result["release-notes"]; // rendered markdown          (string)
result["changelog-entry"]; // one string per release   (string[], from `<multiple:>`)

A <multiple:> block can also declare <name:> to key each item by a computed name instead of array position:

<changelog-by-version>
<multiple: entry in releases>
<name: entry.version>

### {{ entry.version }} — {{ entry.date }}

result["changelog-by-version"];
// { "2.1.0": "### 2.1.0 — 2026-06-01\n", "2.0.0": "### 2.0.0 — 2026-05-01\n" }

renderTemplate(template, inputs) renders an already-parsed template (from parseFile, or a .mdma import emitted by the Vite plugin) — same semantics as render, minus the parse:

import { parseFile, renderTemplate } from "typescript-mdma";

const template = parseFile(source); // parse once ...
renderTemplate(template, { project: "Acme SDK", version: "3.0.0", date: "2026-07-01" }); // ... render many times

renderFile(path, inputs) reads path as UTF-8 and renders it — equivalent to render(readFileSync(path, "utf-8"), inputs):

import { renderFile } from "typescript-mdma";

const result = renderFile("release-notes.mdma", { project: "Acme SDK", version: "3.0.0", date: "2026-07-01" });

writeOutput(result, outputDir, block?) writes a render()/renderFile() result to .md files. Omit block to write every top-level block; pass a block name to write only that one. A string-valued block becomes {outputDir}/{block}.md; a <multiple:> block becomes a directory {outputDir}/{block}/ with one file per item — {name}.md if the block declared <name:>, otherwise {index}.md. Returns the list of paths written.

import { renderFile, writeOutput } from "typescript-mdma";

const result = renderFile("release-notes.mdma", { ... });
writeOutput(result, "out/");                        // every block
writeOutput(result, "out/", "release-notes");        // just that one

getInputs(source) returns the template's @inputs declarations, and validateInputs(source, inputs) checks an inputs object against them without rendering — returning the resolved inputs (defaults applied) or throwing MissingInputError / MdmaTypeError:

import { getInputs, validateInputs } from "typescript-mdma";

getInputs(source);
// [{ name: "project", type: "string", hasDefault: false, default: null }, ...]

validateInputs(source, { project: "Acme SDK", version: "3.0.0", date: "2026-07-01" });
// resolved inputs, with declared defaults applied

Compile-time typed templates¶

Generate a foo.d.mdma.ts declaration next to each foo.mdma so TypeScript knows the template's @inputs shape. Imports are then typed as ParsedTemplate<{...}>, and renderTemplate(template, inputs) (or your own code, via the MdmaInputs<typeof prompt> helper) flags mismatched inputs in the IDE and in tsc:

import prompt from "./createZone.mdma";
import { renderTemplate, type MdmaInputs } from "typescript-mdma";

renderTemplate(prompt, { existing_zone_ids: ["a"] }); // checked against @inputs

const promptInputs = (): MdmaInputs<typeof prompt> => ({
  existing_zone_ids: [], // missing/extra/mistyped keys are compile errors
});

Two ways to keep the declaration files fresh:

Vite plugin (recommended for apps): validates each imported .mdma file at build time, emits its parsed template as the default export (parsed once at module load, never re-parsed), and regenerates the .d.mdma.ts on change.

// vite.config.ts
import mdma from "typescript-mdma/vite";

export default defineConfig({
  plugins: [mdma()], // mdma({ typegen: false }) to only validate + parse
});

Pass { outDir, sourceRoot } instead of a boolean to mirror declarations under a separate directory rather than writing them next to their source — e.g. to gitignore generated files instead of committing them:

plugins: [
  mdma({
    typegen: { outDir: path.resolve(__dirname, "typegen"), sourceRoot: path.resolve(__dirname, "src") },
  }),
],

Pair the same two directories in rootDirs (see below) so allowArbitraryExtensions still finds the mirrored declaration.

CLI (for CI / pre-commit): mdma-typegen [--out-dir <dir>] [path ...] scans for .mdma files and writes their declarations, mirrored under <dir> (relative to whichever path argument found them) when --out-dir is given; mdma-typegen --check exits 1 if any declaration is missing or stale.

Consumer tsconfig.json requirements: enable "allowArbitraryExtensions": true (TypeScript ≥ 5.0) so import x from "./foo.mdma" resolves the adjacent foo.d.mdma.ts, and remove any global declare module "*.mdma" wildcard so the generated per-file types win. If declarations are mirrored under a separate directory via outDir, also add "rootDirs": ["src", "typegen"] (the same two directories) so TypeScript treats them as one virtual directory when resolving the sibling declaration. Type mapping: string/number/boolean map to themselves, object to Record<string, unknown>, arrays to T[]; inputs with a default become optional properties.

render() throws one of the errors in the package on failure:

Error class	Condition
`MissingInputError`	a required input (no default) was not supplied
`MdmaTypeError`	an input's runtime type doesn't match its declared type, or a `<name:>` expression evaluates to something other than a string/number
`MdmaReferenceError`	a forward block reference, or an undefined variable
`FilterError`	a filter was applied to a value of the wrong type
`MdmaSyntaxError`	the `.mdma` source doesn't conform to the grammar (including `<name:>` used without a preceding `<multiple:>`)
`DuplicateNameError`	two items in a `<multiple:>` block computed the same `<name:>` value

All extend MdmaError.

Behavioral notes not obvious from spec.md¶

The blank line conventionally left between one block's content and the next block's header (or EOF) is treated as file formatting, not part of either block's rendered value — it's stripped from both ends of the block body before parsing. This is required for block references ({{ blockname }}) to be safely embeddable inline; otherwise every block value would carry a stray trailing newline from that separator. Blank lines inside a body are preserved exactly as written.
Whitespace control ({%-/-%}) is applied per-tag, exactly as written — a conditional branch that renders empty does not retroactively remove surrounding blank-line text unless that text is trimmed by an adjacent -.
Accessing a missing property on an object/object[] value (e.g. entry.description when description wasn't set) yields null rather than throwing — objects are untyped maps, so this is normal and is what makes | default(...) useful on them. An undefined root identifier (typo'd variable/block/input name) still throws MdmaReferenceError.
default([]) and other array literals ([a, b]) are supported in expressions even though the formal grammar doesn't enumerate an array-literal production — the filter reference relies on this syntax ({{ list | default([]) }}).
This implementation is a from-scratch parser/interpreter (no Jinja/Liquid dependency), matching the Python package behavior exactly — both share the same golden-output test fixtures.
multiple is a reserved word (can't be used as a block or input name), but name is not — <name:> is only ever recognized in its fixed position right after <multiple:>, so an input or block literally named name (e.g. name: string) is unaffected.

Development¶

npm install
npm run typecheck
npm test
npm run build