generated from coulomb/repo-seed
80 lines
1.6 KiB
Markdown
80 lines
1.6 KiB
Markdown
# 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:
|
|
|
|
````markdown
|
|
```python {#helpers}
|
|
def helper():
|
|
return "ready"
|
|
```
|
|
````
|
|
|
|
A chunk becomes an output root when it declares `tangle`:
|
|
|
|
````markdown
|
|
```python {#main tangle="src/app.py"}
|
|
<<helpers>>
|
|
|
|
def main():
|
|
return helper()
|
|
```
|
|
````
|
|
|
|
Chunk references use noweb-style syntax:
|
|
|
|
```text
|
|
<<helpers>>
|
|
```
|
|
|
|
Whole-line chunk references preserve indentation when expanded.
|
|
|
|
## CLI
|
|
|
|
Tangle files:
|
|
|
|
```bash
|
|
mkt tangle examples/literate/app.md --output-dir build/literate
|
|
```
|
|
|
|
Inspect without writing:
|
|
|
|
```bash
|
|
mkt tangle examples/literate/app.md --format json
|
|
```
|
|
|
|
Weave documentation:
|
|
|
|
```bash
|
|
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.
|