mdbook-nix-eval

This is a mdbook preprocessor designed to evaluate code blocks containing nix expressions.

Code blocks with the nix language hint are evaluated and the original expression, and results (or stderr output), are returned to be included in the output document.

```nix
builtins.langVersion
```

Conde blocks with filename-like language hint will be evaluated as above, but also written to a per-chapter temp directory where the file can be referenced later.

```test-file.nix
builtins.langVersion
```

Installation

If you want to use only this preprocessor, install the tool:

cargo install mdbook-nix-eval

Add it as a preprocessor to your book.toml:

[preprocessor.nix-eval]
command = "mdbook-nix-eval"
renderer = ["html"]
#eval_args = "--timeout 5"

Finally, build your book as normal:

mdbook path/to/book

Warnings

• If the nix-builder has sandboxing enabled, there should be limited access to sensitive info, but... it's probably best to only run trusted expressions.
• Network access is allowed in some (most?) cases by the nix sandbox (where available and enabled), so again only trusted expressions are advised.
• nix-instantiate is run with --strict, which the man page say "Warning: This option can cause non-termination, because lazy data structures can be infinitely large." Without the flag, error messages like error: cannot convert a thunk to JSON are much more common.
• Aside from what nix does internally with deterministic outputs, there isn't anything on top of that, so shorter chapters are better if using mdbook serve as each block does call out to nix.

License

MPL. See LICENSE. Copyright (c) 2021 Jason R. McNeil jason@mcneil.dev