mdbook-plotly 0.3.0

A mdbook preprocessor that renders plot code blocks (e.g., ```plot) into interactive or static charts during book build.
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69

# mdbook-plotly

[![GitHub](https://img.shields.io/github/license/TickPoints/mdbook-plotly.svg?style=for-the-badge&logo=github)](https://github.com/TickPoints/mdbook-plotly/blob/master/LICENSE)
[![GitHub Release](https://img.shields.io/github/release/TickPoints/mdbook-plotly.svg?style=for-the-badge&logo=github)](https://github.com/TickPoints/mdbook-plotly/releases)
[![Crates.io](https://img.shields.io/crates/v/mdbook-plotly.svg?style=for-the-badge&logo=rust&color=orange)](https://crates.io/crates/mdbook-plotly)
[![Build Status](https://img.shields.io/github/actions/workflow/status/TickPoints/mdbook-plotly/release.yml?style=for-the-badge&logo=github-actions)](https://github.com/TickPoints/mdbook-plotly/actions)

**English** **[中文](README-zh_CN.md)**

## 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

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

Alternatively, download the latest available release for your system from the [Releases](https://github.com/TickPoints/mdbook-plotly/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`:

```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:

````markdown
```plot
{}
```
````

For more details, refer to the [User Guide](docs/USAGE.md).  

## Parser Notes

- Active parser migration work favors [`translate_with_config!()`](src/macros.rs:36) and [`translate_enum_with_config!()`](src/macros.rs:66) so field resolution stays aligned with the current [`MapEvalConfig`](src/preprocessor/config.rs:61).
- Legacy [`translate!()`](src/macros.rs:29) 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`](docs/USAGE.md).

## License

This project is licensed under the **MIT License**. For full terms, see the [LICENSE](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.