mdbook-plotly

English 中文

Project Overview

mdbook-plotly is a preprocessor for mdbook, which converts specially tagged code blocks (plot or plotly) into interactive charts before generating the final HTML documentation.

It parses chart definitions structured in specific formats (currently supporting JSON5 and TOML) and renders them according to the configured output format (e.g., HTML). Designed specifically for technical documentation, it enables charts to coexist seamlessly with Markdown text while ensuring reproducibility.

Getting Started

Installation

1. Using Cargo

cargo install mdbook-plotly
# If you use binstall:
cargo binstall mdbook-plotly

Alternatively, download the latest available release for your system from the Releases page on GitHub, then add the application’s directory to your system’s PATH environment variable.

2. Add the following to your book.toml:

[preprocessor.plotly]
after = ["links"]
input-type = "json-input"

Use input-type = "toml-input" when the chart block itself is written in TOML. TOML input is converted into a JSON value first, then parsed through the existing plot pipeline.

Generating Charts

Insert a code block where you want the chart to appear, like this:

```plot
{}
```

For more details, refer to the User Guide.

Parser Notes

• Active parser migration work favors translate_with_config!() and translate_enum_with_config!() so field resolution stays aligned with the current MapEvalConfig.
• Legacy translate!() remains available for top-level/defaulted entry points, but new parsing paths should prefer explicit config-aware helpers.
• Chart definitions continue to support map.* references, and the exact expression/generator behavior depends on [preprocessor.plotly.map-eval] plus the optional map-parser-extensions feature set documented in docs/USAGE.md.

License

This project is licensed under the MIT License. For full terms, see the LICENSE file.

Contributing

We welcome contributions of all kinds! Please follow these guidelines:

• Before submitting a Pull Request, open an Issue first to propose new features or discuss bugs.
• Ensure all tests pass (cargo test) and code is properly formatted (cargo fmt).
• Use clear, descriptive commit messages.
• Submit Pull Requests targeting the dev branch.