1.6 KiB
Literate Weave and Tangle
Date: 2026-05-04
Purpose
The literate workflow layer brings a small Knuth-style weave/tangle capability to Markdown without requiring a separate language. Prose stays in Markdown. Named code chunks live in fenced blocks. Tangling emits source files. Weaving keeps the document readable and adds a deterministic chunk index.
Chunk Syntax
Named chunks use fenced block attributes:
```python {#helpers}
def helper():
return "ready"
```
A chunk becomes an output root when it declares tangle:
```python {#main tangle="src/app.py"}
<<helpers>>
def main():
return helper()
```
Chunk references use noweb-style syntax:
<<helpers>>
Whole-line chunk references preserve indentation when expanded.
CLI
Tangle files:
mkt tangle examples/literate/app.md --output-dir build/literate
Inspect without writing:
mkt tangle examples/literate/app.md --format json
Weave documentation:
mkt weave examples/literate/app.md --output build/app-woven.md
Diagnostics
Tangling reports structured diagnostics for missing chunks and cyclic chunk references. Tangled files are only written by the CLI when the result is valid.
Extension Boundary
The MVP deliberately keeps the model narrow:
- named fenced blocks
tangle="<path>"- deterministic document-order concatenation for repeated targets
- noweb-style chunk expansion
- generated chunk index during weave
Future extensions can add richer source maps, processor execution, language-specific extraction, and class/namespace-aware chunk selection without changing this initial chunk model.