Gribouille

Create elegant graphics with the Grammar of Graphics for Typst.

Gribouille is French for "scribble". The library implements Wilkinson's Grammar of Graphics in a declarative API for Typst documents, inspired by ggplot2 (R) and plotnine (Python).

Documentation: https://m.canouil.dev/gribouille.

[!WARNING] Gribouille is in active development.

Quick look

#import "@preview/gribouille:0.7.0": *

#let species-colours = (
  Adelie: rgb("#ff8c00"),
  Chinstrap: rgb("#008B8B"),
  Gentoo: rgb("#800080"),
)

#plot(
  data: penguins,
  mapping: aes(
    x: "flipper-len",
    y: "body-mass",
    colour: "species",
    fill: "species",
    shape: "species",
  ),
  layers: (
    geom-point(size: 2pt, alpha: 0.25, stroke: 0.5pt, colour: rgb("#ffffff")),
    geom-smooth(method: "lm", se: true, alpha: 0.2),
    geom-mark(method: "hull", expand: 5pt, alpha: 0.25),
    geom-errorbar(stat: stat-summary(fun: "mean-sd"), width: 5pt),
    geom-errorbarh(stat: stat-summary(fun: "mean-sd"), height: 5pt),
    geom-label(
      stat: stat-summary(fun: "mean"),
      mapping: aes(label: "species"),
      colour: rgb("#ffffff"),
      size: 8pt,
    ),
  ),
  scales: scales(
    x: scale-continuous(),
    y: scale-continuous(labels: format-comma()),
    colour: scale-discrete(
      limits: species-colours.keys(),
      palette: species-colours.values(),
    ),
    fill: scale-discrete(
      limits: species-colours.keys(),
      palette: species-colours.values(),
    ),
  ),
  labels: labels(
    title: typst("Penguins *Dataset*"),
    subtitle: typst({
      [Flipper length vs body mass by species: ]
      species-colours
        .pairs()
        .map(p => text(fill: p.at(1), weight: "bold")[#p.at(0)])
        .join(", ")
    }),
    caption: "Data from Palmer Archipelago (Antarctica) penguin dataset.",
    colour: "Species",
    fill: "Species",
    shape: "Species",
    x: "Flipper Length (mm)",
    y: "Body Mass (g)",
  ),
  theme: theme-minimal(),
  width: 12cm,
  height: 9cm,
)

AI assistants

The documentation ships a machine-readable copy for large language models at https://m.canouil.dev/gribouille/llms.txt. Every page also has a .llms.md companion.

An installable skill teaches coding agents to author Gribouille plots against that reference. Install it with the agent-neutral skills CLI:

npx skills add mcanouil/gribouille

The repository also doubles as a plugin marketplace:

/plugin marketplace add mcanouil/gribouille
/plugin install gribouille@gribouille

See the AI Assistants guide for details.

Dependencies

See typst.toml and src/deps.typ for the authoritative Typst compiler and CeTZ versions.

Contributing

[!NOTE] Gribouille is an unfunded spare-time project, and the API is still settling. Bug reports and ideas are welcome on the issue tracker.

I do not accept pull requests for now. The internals shift between releases. Every review costs time that I must take from the work that moves the library forward. I am also especially careful in the current climate of unreviewed LLM-authored patches. Once the surface is stable I will revisit and open the door.

Thanks in advance for your patience and your understanding.

Contributions are welcome. See CONTRIBUTING.md for bug reporting, development setup, and commit conventions. Short identifiers used across the source tree (ctx, spec, mapping, cx, cy, lo, hi, …) are catalogued in GLOSSARY.md.

Citation

If you use Gribouille in your work, cite it. Citation metadata is provided in CITATION.cff. GitHub renders it via the "Cite this repository" widget on the repository sidebar.

License

This project is licensed under the MIT License. See the LICENSE file for details.