2.1 KiB
Explode and Implode
Date: 2026-05-04
Purpose
mkt explode and mkt implode reintroduce the useful old Markitect
large-document workflow as a slim WP-0010 extension. The design is
manifest-first: the exploded directory is editable, but the manifest preserves
ordering, source spans, heading metadata, hashes, frontmatter, and the selected
layout variant.
This keeps the operation reversible without requiring a database or service.
Variants
The initial variants are:
flat: writes ordered section files undersections/.hierarchical: writes child section files below parent heading directories.
Both variants preserve the same manifest model. A later semantic variant can reuse the reference and processor framework once those layers are stable.
CLI
Explode a document:
mkt explode docs/source.md --output-dir work/source-exploded
Use a hierarchical directory shape:
mkt explode docs/source.md --output-dir work/source-tree --variant hierarchical
Implode the directory back into one Markdown file:
mkt implode work/source-exploded --output docs/source-rebuilt.md
By default mkt explode refuses to write into a non-empty output directory. Use
--force when an explicit overwrite is intended.
Manifest
The manifest is written as markitect-explode.yaml in the output directory.
It records:
- manifest version
- original source path and SHA-256 hash
- variant
- raw frontmatter block
- ordered entries with file path, kind, unit ID, source line span, heading metadata, and content hash
Implode reads the manifest entries in order and concatenates the current entry files. If users edit section files, the rebuilt document reflects those edits while preserving the original frontmatter and ordering.
Extension Boundary
This implementation is intentionally not semantic yet. It does not infer contracts, classes, named chunks, or processor outputs. Instead it establishes a small reversible substrate that later WP-0010 tasks can enrich with regions, references, processors, source maps, and weave/tangle behavior.