How to add an example

Documentation examples are small Python scripts that generate committed HTML iframes. The docs pages then embed those iframes.

Pick the right place¶

Use an existing guide when the example teaches one feature, such as tooltips, CSS, JavaScript, animation, or an integration.

Use the gallery when the example is a complete chart that readers may want to copy or adapt.

If the example needs CSS, JavaScript, or local data, keep those support files in docs/examples/ too. Existing examples use names such as area_hover_to_show.css, area_hover_to_show.js, and household-wealth.csv.

Write the Python script¶

Create a script in docs/examples/. It should run from the repository root because just examples runs every file as uv run docs/examples/<file>.py.

Keep the script focused:

• import only what the example needs
• build one plotnine chart
• add tooltip, hover_group, or on_click only when the example needs them
• save to docs/iframes/<slug>.html
• use minify=True so the committed iframe stays small

Template:

from plotnine import aes, geom_point, ggplot, theme_minimal
from plotnine.data import mtcars

from ninejs import interactive, save


gg = (
    ggplot(mtcars, aes("wt", "mpg", tooltip="name"))
    + geom_point(size=5, alpha=0.7)
    + theme_minimal()
)

interactive(gg) + save("docs/iframes/my-example.html", minify=True)

If the example uses custom CSS or JavaScript, load it from docs/examples/:

from ninejs import css, interactive, javascript, save

(
    interactive(gg)
    + css(from_file="docs/examples/my-example.css")
    + javascript(from_file="docs/examples/my-example.js")
    + save("docs/iframes/my-example.html", minify=True)
)

Add the docs page¶

For a gallery example, create docs/gallery/<slug>.md.

Use a short introduction, show the code, then embed the generated iframe:

---
title: My example
---

- Source: [Original chart](https://example.com)
- Author: [Original author](https://example.com)

This example shows how to use `tooltip` and `hover_group` together.

```py hl_lines="4 18"
from plotnine import aes, geom_point, ggplot, theme_minimal
from plotnine.data import mtcars

from ninejs import interactive, save


gg = (
    ggplot(mtcars, aes("wt", "mpg", tooltip="name", hover_group="cyl"))
    + geom_point(size=5, alpha=0.7)
    + theme_minimal()
)

interactive(gg) + save("docs/iframes/my-example.html", minify=True)
```

<iframe width="100%" height="600" src="../iframes/my-example.html" style="border:none;"></iframe>

The iframe path depends on where the Markdown page lives:

Update navigation¶

If you added a new page, register it in zensical.toml.

Gallery pages go under the Gallery nav. Contributing pages go under the Contributing nav. If you only added a new example section to an existing guide page, the nav usually does not need to change.

For gallery examples, also add a link and iframe preview to docs/gallery/index.md.

Check the result¶

Run the new script first:

uv run docs/examples/my-example.py

Then regenerate all examples:

just examples

Preview the docs:

just doc

Common mistakes¶