| title | Generating Content with Directives |
|---|---|
| summary | How to use catalog and include directives to generate and embed content in Markdown files. |
mdsmith can generate content inside your Markdown
files. Two directives handle this: <?catalog?> for
building file indexes and <?include?> for embedding
content from other files. Both regenerate their body
on mdsmith fix and flag stale content on
mdsmith check.
Use <?catalog?> when you need a list of files with
metadata — for example, a table of plans, a docs
index, or a rule directory. For the agent-facing
docs index, see
Progressive Disclosure for AI Agents.
The simplest form lists all matching files as a bullet list:
<?catalog
glob: "docs/**/*.md"
?>
- [cli.md](design/cli.md)
- [index.md](development/index.md)
<?/catalog?>Without row, header, or footer, the directive
outputs - [<basename>](<path>) per file, sorted by
path.
Add row (and optionally header, footer) to
control the output format. Use {field} placeholders
to pull front matter values from matched files:
<?catalog
glob: "plan/*.md"
sort: id
header: |
| ID | Title |
|----|-------|
row: "| {id} | [{title}]({filename}) |"
?>
| 74 | [Directive guide](plan/74_directive-guide.md) |
| 75 | [Single-brace placeholders](plan/75_single-brace-placeholders.md) |
<?/catalog?>{field} placeholders reach scalar front-matter
values only. To project a list — multiple authors
per file, multiple peer-linter mappings on a rule
README, multiple tags — switch the directive from
row: to row-expr:. The value is a CUE
expression. Every identifier-safe key in the
matched file's front matter binds at top-level
scope. The expression must return a string.
<?catalog
glob: "internal/rules/MDS*/README.md"
where: 'category: "heading"'
sort: id
row-expr: |
"| \(id) | " +
strings.Join(
[for m in markdownlint {
"\(m.id) \([if m.default {"✅"}, if !m.default {"⚪"}][0]) \(m.name)"
}],
", "
) + " |"
?>
<?/catalog?>The strings standard-library package is
preimported. CUE has no infix ternary; pick
between two values with the
[if cond {a}, if !cond {b}][0] list-comprehension
idiom. row and row-expr are mutually exclusive
on one directive. columns: width constraints
apply to row only.
glob accepts a YAML list to collect files from
several directories:
<?catalog
glob:
- "docs/**/*.md"
- "plan/*.md"
sort: path
row: "- [{title}]({filename})"
?>Prefix a glob pattern with ! to exclude matching
files. Exclusion patterns use the same glob syntax as
include patterns:
<?catalog
glob:
- "**/*.md"
- "!drafts/**"
- "!internal/notes.md"
row: "- [{title}]({filename})"
?>At least one non-negated (include) pattern is required. Excludes and includes are collected into separate lists — a file matching any exclude pattern is filtered out regardless of where the pattern appears in the list.
By default, files matched by .gitignore rules are
excluded from catalog results. To include gitignored
files, set gitignore: "false":
<?catalog
glob: "**/*.md"
gitignore: "false"
?>The where parameter narrows the matched set by a CUE
expression
evaluated against each file's parsed front matter. The
expression grammar is the same one
mdsmith list query
accepts, so a CLI query expression drops in unchanged:
<?catalog
glob: "internal/rules/MDS*/README.md"
where: 'nature: "directive"'
row: "- [{name}]({filename})"
?>
<?/catalog?>The filter runs after globbing and front matter parsing, but before sort and render. Failure modes:
- An invalid CUE expression triggers an MDS019 diagnostic on the directive's opening line.
- A file whose front matter is missing the referenced field is excluded (no diagnostic).
- A field whose value does not satisfy the constraint (wrong type or wrong value) is excluded.
Format: [-][numeric:]KEY. A - prefix means
descending. Built-in keys: path, filename. Any
other key is looked up in front matter. Missing
values sort as empty string.
The optional numeric: prefix opts a field into
integer comparison. Use it for ID-shaped fields
where mixed 2-digit and 3-digit values would
otherwise collate lexicographically (100 before
52):
<?catalog
glob: "plan/*.md"
sort: numeric:id
row: "| {id} | [{title}]({filename}) |"
?>If any matched file's value fails to parse as an
integer, the directive falls back to string
compare for all entries — no error is raised, so a
field that is sometimes numeric stays usable.
-numeric:id reverses the order.
If empty is defined, its text is used. Otherwise
zero lines appear between the markers.
For full parameter reference, see MDS019 catalog.
Use <?include?> when you want to embed the content
of another file — for example, sharing a development
guide across README and docs, or including a config
file as a code block.
<?include
file: DEVELOPMENT.md
strip-frontmatter: "true"
?>
Build and test reference for contributors.
<?/include?>By default, YAML front matter is stripped. Set
strip-frontmatter: "false" to keep it.
Include a non-Markdown file wrapped in a fenced code block:
<?include
file: config.yml
wrap: yaml
?>
```yaml
key: value
```
<?/include?>heading-level takes "absolute" or an integer 1-6.
Use "absolute" when including under an existing heading,
to shift included headings so they nest correctly:
## Project
<?include
file: DEVELOPMENT.md
heading-level: "absolute"
?>
### Build
Steps here.
<?/include?>Without this parameter, included headings keep their original level, which may break heading hierarchy.
Use an integer to pin the shallowest included heading to
that level, whatever the source or parent — handy at the
document root, where "absolute" is a no-op:
<?include
file: features.md
heading-level: "2"
?>
## Pinned To Level 2
<?/include?>heading-level is mutually exclusive with heading-offset.
To shift every included heading by a fixed amount, use
heading-offset with a signed integer from -6 to 6:
<?include
file: features.md
heading-offset: "1"
?>
## Was An H1 In The Source
<?/include?>A positive value demotes headings; a negative value
promotes them. Unlike heading-level: "absolute", the
shift does not depend on a preceding heading, so it also
works at the document root — handy when a file's visual
title is a logo or image rather than an H1.
heading-offset cannot combine with heading-level or
extract: — those parameters are mutually exclusive with
it.
Relative links in included content are automatically rewritten to resolve from the including file's directory. Absolute URLs and protocol links are not modified.
Include chains are tracked. Circular includes and chains deeper than 10 levels are rejected:
cyclic include: a.md -> b.md -> a.md
When the target file is kind-typed, extract: walks
the same JSON projection
mdsmith extract
produces and splices a single leaf. The value is a
dotted path: frontmatter.title reaches the title
field; tagline.text reaches the paragraph under
the ## Tagline heading; a section whose body is a
fenced code block is reached through its .code key.
A paragraph section. The target's
## Tagline heading projects to {"tagline": {"text": "..."}}, so the path tagline.text lands
on the prose:
<?include
file: docs/brand/messaging.md
extract: tagline.text
?>
Markdown, fast.
<?/include?>A fenced code block. A section whose body is a
single fenced code block projects its contents under
a code key. Given a file setup.md whose
## Setup section holds an install command, the
projection is {"setup": {"code": "..."}}, and
setup.code splices the code body verbatim:
<?include
file: setup.md
extract: setup.code
?>
go install github.com/jeduden/mdsmith/cmd/mdsmith@latest
<?/include?>A frontmatter scalar. Every kind-typed file's
projection carries a top-level frontmatter object
beside the body sections. The path is
frontmatter.<key>:
<?include
file: docs/brand/messaging.md
extract: frontmatter.title
?>
mdsmith product messaging
<?/include?>Single-content-key shortcut. A leaf object that
carries exactly one of text, code, inline,
items, or rows resolves to the inner value, so
extract: tagline and extract: tagline.text
splice the same content. An inline value is a
typed span list rather than a scalar, so it cannot
be spliced yet and surfaces as a lint error.
Multi-key wrappers (the JSON projection of a
section with several content entries) are ambiguous
and surface as a lint error with the available keys
listed.
Restrictions. extract: is scalar-only for now —
combining it with strip-frontmatter: or
heading-level: is rejected. A target file with no
resolved kind is rejected too: without a schema there
is no projection to walk. A target whose body fails
required-structure surfaces the same diagnostic
mdsmith check would raise on the target, anchored
to the include directive's call site.
For full parameter reference, see MDS021 include.
Both directives are only recognized at document root (parent must be the Document node). Maximum indent is 3 spaces.
Directives are not recognized inside list items, blockquotes, tables, fenced code blocks, or HTML blocks.
4-space indent footgun: 4 or more leading spaces turns the line into a code block. The directive is silently ignored with no error. Always use 0-3 spaces.
Same-type nesting is supported. When an included file
contains its own generated sections (include, catalog,
etc.), the inner markers are treated as literal content
of the outer directive. FindMarkerPairs pairs only the
outermost markers of each directive type; inner markers
are skipped. Cross-type directives between markers may
appear but are overwritten by the outer generator on
fix.
{field} is the only placeholder syntax. It works in
row templates and schema headings.
{filename}— relative path from the marker file.{title},{summary}— looked up in front matter.- Missing field — empty string.
- Case mismatch — "did you mean?" hint.
- Non-string scalar — formatted to string. Composite values (maps, slices) — empty string.
- Literal
{— write{{. Literal}— write}}.
CUE paths provide nested access for structured front matter values.