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(...).

Heading shifts are token-safe: Markdown fenced and indented code blocks are left untouched even if their lines look like headings. TransformResult includes structured provenance events alongside the older operation-name list.

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.
• Include markers inside fenced or indented code blocks are left literal.

The API equivalent is resolve_includes(...).

IncludeResult includes structured provenance events. Each include event records the source marker line when available, the resolved target path, dependency edge, selector, heading shift, and frontmatter policy. This is the first provenance envelope used by later WP-0010 processor, source-map, and explode/implode work.