# 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.