Interactive Markdown brings the spirit of Literate Programming — championed by Donald Knuth and popularized in data science by tools like R Markdown — to the MeshWeaver platform. The idea is simple: code lives alongside the prose that explains it, and that code actually runs.

How It Works

MeshWeaver extends standard Markdown fenced code blocks with a small set of flags in the block header, much like command-line arguments. The most important flag is --render:

--render <area>

area is the name of the layout area that will be injected into the rendered document at the location of the code block. When the document loads, MeshWeaver allocates a lightweight kernel, executes the block, and streams the result back into the page.

Displaying the Code

Two flags control whether readers see the source alongside the output:

Example — full header visible:

```csharp --render HelloWorld --show-header
"Hello World " + DateTime.Now.ToString()
```

Example — code visible, header hidden:

"Hello World " + DateTime.Now.ToString()

Execution Pipeline

When a page containing executable blocks is opened, the following sequence runs automatically:

The kernel runs each block in document order, stores every named result as a layout area, and the Markdown component replaces each --render placeholder with the live output. No page reload is needed.

Mermaid Diagrams

Mermaid diagrams are supported natively — just declare them as a fenced code block with the mermaid language tag. The diagram above was produced this way:

```mermaid
sequenceDiagram
    participant View
    participant Article
    participant Kernel
    View->>Article: Requests Content
    Article->>Kernel: Submits Code Execution
    Article->>View: Issues HTML
    View->>Kernel: Requests Layout Area
    Kernel->>View: Returns Layout Area
```

Refer to the Mermaid documentation for the full range of supported diagram types (flowcharts, class diagrams, Gantt charts, and more).

Prompt Fences

Not every live block is code. A ```prompt fence carries a suggested prompt for an agent, and it renders as a composer the reader can edit in place:

```prompt
Show two versions of the same movement report: one with a single "unexplained"
balancing line, one with the movement broken out.
```

The fence body becomes the composer's initial draft. The reader changes whatever they like, presses Submit, and a real agent thread starts seeded with what they actually typed — opening full page, with the page the prompt was authored on carried along as the thread's context.

There are no flags. A prompt fence never reaches the kernel: it is prose for an agent, not source.

Wherever the composer cannot be put on the page — an exported document, or a page with no owning node behind it — the fence renders as an ordinary read-only block, so the prompt is never lost.

Live Example

The cell below runs on page load and renders a small layout control into the document — a minimal demonstration of the --render + --show-code combination in action:

MeshWeaver.Layout.Controls.Markdown($"**Interactive Markdown is live.** This cell executed at {DateTime.Now:HH:mm:ss} on {DateTime.Now:yyyy-MM-dd}.")

Why this matters. Documentation that executes its own examples can never silently drift out of date — a broken example is a build failure, not a future support ticket.

Adding a fence of your own

The dialect above is not closed — but extending it is not a one-repo edit either. The platform parses a fence and emits an inert HTML marker; whichever client is rendering the page is what turns that marker into something interactive, and every client lives outside this repository. See Markdown Fence Extensions for the seam, the two markers that already exist (reuse one rather than mint a third), and the degradation rule that keeps a new fence from rendering as less than the plain fenced block it replaced.