# mdbook-nix-eval
This is a [mdbook](https://crates.io/crates/mdbook) preprocessor designed to evaluate code blocks containing [nix](https://nixos.org/) 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:
```sh
cargo install mdbook-nix-eval
```
Add it as a preprocessor to your `book.toml`:
```toml
[preprocessor.nix-eval]
command = "mdbook-nix-eval"
renderer = ["html"]
#eval_args = "--timeout 5"
```
Finally, build your book as normal:
```sh
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](LICENSE).
Copyright (c) 2021 Jason R. McNeil <jason@mcneil.dev>