@holdenmatt/md-slots

Tiny {{slot}} renderer for markdown text.

Install

npm install @holdenmatt/md-slots

Usage

import { renderSlots, slots } from "@holdenmatt/md-slots";

const template = "Hello {{ name }}.\n\n{{body}}";

slots(template);
// ["name", "body"]

renderSlots(template, {
  name: "Ada",
  body: "Welcome.",
});
// "Hello Ada.\n\nWelcome."

Dot paths resolve through objects and arrays:

renderSlots("Hello {{ user.name }} from {{items.0.title}}.", {
  items: [{ title: "Markdown" }],
  user: { name: "Ada" },
});
// "Hello Ada from Markdown."

API

slotOccurrences(template: string): string[]

Returns normalized slot names in authored order, including duplicates. This is the lower-level API for callers that need every occurrence. Malformed placeholders are ignored.

slots(template: string): string[]

Returns unique slot names in order of first appearance. Slots look like {{name}} or {{path.to.value}}, with ignored whitespace inside the braces.

renderSlots(template, values, options?): string

Replaces matching slots with values[name]. Dotted slots resolve through nested objects and arrays, so {{user.name}} reads values.user.name and {{items.0.name}} reads the first item's name.

Exact top-level keys win before path resolution: if values has an own key named "a.b", {{a.b}} uses that value instead of values.a.b.

Strings render as-is; other values render with JSON.stringify(value, null, 2). Pass options.format(value, name) to customize formatting for present values.

Use options.missing to control missing, null, and undefined values:

| Value | Behavior | Use for | | --------- | ---------------------------------------------------------------- | ----------------------------------- | | "throw" | Throws Error("Missing slot: <name>"). This is the default. | Runtime rendering | | "keep" | Leaves the exact matched slot text unchanged, including spacing. | Previews with visible unbound slots | | "empty" | Renders an empty string without trimming surrounding whitespace. | Optional-value fills |

@holdenmatt/md-slots is markdown-agnostic: it replaces matching tokens anywhere in the input, including code fences.