generated from coulomb/repo-seed
70 lines
2.1 KiB
Markdown
70 lines
2.1 KiB
Markdown
# 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 under `sections/`.
|
|
- `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:
|
|
|
|
```bash
|
|
mkt explode docs/source.md --output-dir work/source-exploded
|
|
```
|
|
|
|
Use a hierarchical directory shape:
|
|
|
|
```bash
|
|
mkt explode docs/source.md --output-dir work/source-tree --variant hierarchical
|
|
```
|
|
|
|
Implode the directory back into one Markdown file:
|
|
|
|
```bash
|
|
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.
|