Zorto can execute Python and Bash code blocks at build time and render their output inline.

WriteMarkdown with code blocks
→
ParseFind executable blocks
→
ExecuteRun via PyO3 or shell
→
RenderOutput inlined in HTML

Python blocks #

Use the {python} language tag:

```{python}
import math
print(f"Pi is approximately {math.pi:.4f}")
```

At build time, Zorto runs the code and inserts the output below the block.

Bash blocks #

Use the {bash} (or {sh}) language tag:

```{bash}
echo "Hello from $(uname)"
date +%Y-%m-%d
```

File attribute #

Run a script file instead of inline code:

```{python file="scripts/analysis.py"}
```

The file path is relative to the content file’s directory.

Disabling execution #

To build without executing code blocks:

zorto --no-exec build

This renders the code blocks as plain syntax-highlighted code.

Output rendering #

  • stdout is captured and displayed as a code block below the source
  • stderr is displayed as a warning block
  • Non-zero exit codes produce an error block with the return code

Tip

Executable code blocks are great for keeping CLI references up to date. Use zorto --help in a {bash} block and the docs always match the current version.

Python runtime #

Zorto embeds Python via PyO3 — code blocks run in-process, not by shelling out. If a .venv directory exists at or above the site root (or VIRTUAL_ENV is set), Zorto activates its site-packages automatically, giving code blocks access to installed packages.

Security considerations #

Executable code blocks run with the same permissions as the zorto process. In CI environments, treat executable code blocks like any other build script — review content before building untrusted markdown. Use zorto --no-exec build to skip execution when building untrusted content.

Further reading #