mdbook-uplot

An mdbook preprocessor for embedding interactive uPlot charts in your book.

Write chart data as fenced ```uplot code blocks in your markdown and mdbook-uplot renders them as interactive charts.

Quick example

Features

• Bar, line, area, and scatter chart types
• Interactive — tooltips, hover crosshair, drag-to-zoom
• Customizable — hide legend, disable tooltips, set axis ranges, pass any uPlot option via opts
• Zero runtime dependencies — all assets are bundled in the binary
• Dark theme support — automatically adapts to mdbook’s coal, navy, and ayu themes

Installation

Shell (macOS/Linux)

curl --proto '=https' --tlsv1.2 -LsSf https://github.com/n1ght-hunter/mdbook_uplot/releases/latest/download/mdbook_uplot-installer.sh | sh

PowerShell (Windows)

powershell -ExecutionPolicy ByPass -c "irm https://github.com/n1ght-hunter/mdbook_uplot/releases/latest/download/mdbook_uplot-installer.ps1 | iex"

cargo-binstall

cargo binstall mdbook_uplot

From crates.io

cargo install mdbook_uplot

Setup

Add the preprocessor to your book.toml:

[preprocessor.uplot]

Then either run mdbook build twice (the first run writes the asset files and updates book.toml, the second picks up the changes), or add the following to book.toml manually:

[output.html]
additional-js = ["assets/uplot/uplot.min.js", "assets/uplot/uplot-bars.js", "assets/uplot/uplot-init.js"]
additional-css = ["assets/uplot/uplot.min.css", "assets/uplot/uplot-charts.css"]

Alternatively, run the install command to do everything in one step:

mdbook-uplot install /path/to/book

Usage

Use fenced code blocks with the uplot language tag to create charts.

```uplot
{
  "type": "line",
  "labels": [1, 2, 3, 4],
  "datasets": [
    { "label": "Series 1", "data": [10, 20, 15, 30] }
  ]
}
```

Chart types

Set the type field to choose a chart style:

See the sub-pages for examples and type-specific options.

Common fields

Custom uPlot options

The opts field lets you deep-merge arbitrary options into the uPlot configuration. This gives access to uPlot’s full API without needing custom JS:

```uplot
{
  "type": "line",
  "labels": [1, 2, 3, 4, 5],
  "datasets": [{ "label": "Value", "data": [10, 25, 18, 32, 28] }],
  "opts": {
    "scales": { "y": { "range": [0, 50] } }
  }
}
```

External data files

Instead of inlining data, reference a JSON file:

```uplot
{ "data": "path/to/data.json" }
```

Paths are resolved relative to the chapter’s source directory. The referenced file should contain the same JSON structure (with type, labels, datasets, etc.).

Bar Charts

Basic bar chart

Multiple series

Options

Line Charts

Basic line chart

Multiple series

With points and dashes

Set "points": true to show data points, and "dash": [5, 3] for dashed lines:

Dataset options

Area Charts

Area charts are line charts with a filled region below the line.

Basic area chart

Stacked look with multiple series

Custom fill opacity

By default the fill is 30% opacity of the line color. Override with a custom fill value:

Dataset options

Scatter Charts

Scatter charts display individual data points without connecting lines.

Basic scatter chart

Multiple series

Custom point size

Dataset options

Customization

Hide legend

Use "legend": { "live": true } to show live values at the cursor position instead of the default static legend.

Hide tooltip

Enable crosshair

Show vertical and horizontal hover lines (disabled by default):

Disable hover points

Enable drag-to-zoom

Double-click to reset zoom.

Custom axis range

Custom height

Combining options

All fields can be combined:

Value formatting

Use format to control how values appear in tooltips and y-axis ticks:

Per-dataset format overrides the global one:

Show all series in tooltip

By default the tooltip shows only the nearest series. Use "tooltip": { "all": true } to show all series at the cursor position:

Code display

By default every chart shows Chart | Code tabs. Use the code field to change where and how the code appears:

Hide code entirely

Code below the chart

Collapsible below (closed by default)

Collapsible below (open by default)

Code above the chart

Side by side

On narrow screens the side-by-side layout stacks vertically.

Options reference

Editable playground

Set "editable": true to let readers edit the JSON and see the chart update live. Try changing the data or colors below:

Advanced: opts reference

The opts field is deep-merged into the uPlot configuration before chart creation. Any valid uPlot option can be passed here, including cursor, scales, axes, select, and more.