markitect-tool/docs/transform-compose-include.md

Transform, Compose, and Include Primitives

markitect-tool keeps document operations deterministic and Markdown-native. The first operation layer covers three practical needs:

• Transform one document with explicit operations.
• Compose several Markdown files into one output.
• Resolve Markdown include markers without adding a service or database layer.

These operations are deliberately small. They are meant to be reliable building blocks for later templates, generation, cache backends, and agent workflows.

Transform

Use mkt transform for deterministic edits that can be repeated in a pipeline:

mkt transform doc.md --set status=draft --heading-delta 1

Supported operations:

• --set KEY=VALUE: set frontmatter values. Dot paths create nested mappings.
• --strip-frontmatter: remove frontmatter.
• --heading-delta N: shift ATX headings and clamp levels to # through ######.
• --extract SELECTOR: replace document content with selector output.

The API equivalent is transform_markdown(...).

Compose

Use mkt compose to concatenate Markdown inputs with predictable separators:

mkt compose intro.md details.md --title "Combined Document" --output combined.md

By default, each input file's YAML frontmatter is removed before composition. Use --include-frontmatter when the frontmatter itself should be preserved in the composed body.

The API equivalent is compose_files(...).

Include

Use mkt include to resolve transclusion markers:

Before.

<!-- mkt:include path="sections/intro.md" -->

After.

The explicit marker supports attributes:

<!-- mkt:include path="sections/intro.md" selector="sections[heading=Summary]" heading_delta="1" -->

Supported attributes:

• path: required relative path to the included Markdown file.
• selector: optional Markitect selector; only matching content is included.
• heading_delta: optional heading-level shift for included content.
• include_frontmatter: true keeps the included file's frontmatter.

The compact shorthand is also supported:

{{include:sections/intro.md}}

Resolution rules:

• Relative paths resolve from the including file.
• All included paths must stay under --base-dir, defaulting to the input file directory.
• Recursive includes are resolved up to --max-depth.
• Cycles and missing files fail with explicit errors.

The API equivalent is resolve_includes(...).