generated from coulomb/repo-seed
95 lines
3.0 KiB
Markdown
95 lines
3.0 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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:
|
|
|
|
```markdown
|
|
Before.
|
|
|
|
<!-- mkt:include path="sections/intro.md" -->
|
|
|
|
After.
|
|
```
|
|
|
|
The explicit marker supports attributes:
|
|
|
|
```markdown
|
|
<!-- 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:
|
|
|
|
```markdown
|
|
{{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.
|