Gribouille 0.3.0: A Grammar of Graphics for Typst

Nearly 80 % of business decisions are driven by visual data, yet more than half of analysts spend over 30 % of their time wrestling with formatting instead of insight‑generation. With Gribouille 0.3.0 you can cut that wasted time in half—turning raw data into polished, interactive dashboards directly inside Typst, the next‑gen typesetting system. Imagine drafting a quarterly report, tweaking a chart, and seeing the result instantly rendered in the same document you’ll print for the board—no Photoshop, no PowerPoint, no copy‑paste.

In This Article

• What is Gribouille?
• Setting Up Gribouille in Your Analytics Workflow
• Building Business‑Ready Visualizations
• Why It Matters: Real‑World Impact on Data Analysis & Decision‑Making
• Actionable Takeaways & Next Steps
• Frequently Asked Questions

What is Gribouille? A Quick Primer

Gribouille is a lightweight, declarative package that brings the grammar of graphics to Typst. Think of it as the R equivalent of ggplot2, but written in a way that fits snugly into a document that also contains prose, footnotes, and equations. The core idea is simple: you describe what you want to see—data, aesthetics, geometry—and the library builds the visual for you.

Why Typst, you ask? Typst produces clean, native PDF output, which is a big win for print‑ready reports. Its syntax is declarative, meaning you write code that looks almost like a sentence: #gribouille(data: sales, mapping: (x: "Quarter", y: "Revenue")). That keeps your code readable and your documents tidy.

Version 0.3.0 adds layered faceting, custom themes, and built‑in interactivity hooks. Now you can split a single chart into multiple panels based on a category, apply a corporate palette with one line, and embed tooltips that show up in PDF viewers that support them.

Setting Up Gribouille in Your Analytics Workflow

First things first: add Gribouille to your typst.toml file.

[dependencies]
gribouille = "0.3.0"

Once that’s in place, you’re ready to pull in data. Typst can read CSV and JSON out of the box. For a quick start, let’s assume you’ve got a sales.csv file in a data folder. Inside your report.typ file, you’ll write:

#let sales = csv("data/sales.csv")

Now you have a table you can feed straight into Gribouille.

Here’s a minimal bar chart that takes just five lines of code. Seriously, it’s that short.

#gribouille(
  data: sales,
  mapping: (x: "Region", y: "Revenue"),
  geom: "bar",
  title: "Revenue by Region"
)

Compile with typst compile report.typ and you’ll see your chart appear in the PDF. No manual scaling, no color swatches, no manual axis tweaking—just pure data visualization that updates automatically whenever you edit the CSV.

Building Business‑Ready Visualizations

We’re not just talking about pie‑charts for the sake of a pie. Gribouille gives you a full suite of chart types that you can drop into dashboards or reports: bar, line, scatter, heatmap, and even geo‑maps if your data includes latitude and longitude. Let’s walk through a line chart that tracks a KPI over time.

#gribouille(
  data: sales,
  mapping: (x: "Month", y: "Profit"),
  geom: "line",
  theme: "corporate",
  title: "Monthly Profit Trend"
)

Custom palettes are a breeze. If your brand uses a specific color scheme, just declare it once and reuse it across all charts. Gribouille’s theme engine respects fonts, background colors, and even grid line styles. That means a single palette tweak can make your entire report look cohesive.

Embedding in multi‑page reports is straightforward. Use #gribouille wherever you would normally place a figure, add a caption and label, and then reference it from the text. Because everything lives in the same markup file, you don’t have to juggle separate graphic files or worry about mismatched titles.

Why It Matters: Real‑World Impact on Data Analysis & Decision‑Making

Speed and reproducibility are the twin engines of modern analytics. With one source of truth—your .typ file and the data it references—you can regenerate a report in seconds instead of hours. That means analysts spend less time formatting and more time interpreting.

Collaboration improves too. Plain‑text files play nicely with Git. Commit your report.typ and the CSV, and you can track every tweak, roll back a bad change, or merge contributions from teammates without headaches.

Picture this: a fintech company that used to spend five days assembling a quarterly dashboard. After adopting Gribouille 0.3.0, they cut that to just one day. The reason? The charts are generated from code, so they could tweak a single line and have the entire report update. No more manual copy‑paste, no more misaligned axes.

Actionable Takeaways & Next Steps

• Install Gribouille via typst.toml.
• Load data with #let.
• Choose a chart type and map aesthetics.
• Apply a custom theme to match your brand.
• Compile to PDF and share.

Resources: the official GitHub repo, community templates, and the documentation page that walks through every option.

Future‑proofing is as simple as integrating Gribouille into a CI pipeline. Every time your data source updates, run typst compile and push the fresh PDF to your repository. Your dashboards stay current automatically.

Frequently Asked Questions

What is the difference between Gribouille and ggplot2?

Gribouille implements the same grammar‑of‑graphics principles as ggplot2 but is built for Typst’s declarative markup language, producing native PDF output without needing an external graphics engine. It’s ideal for reports where text and graphics must stay perfectly aligned.

Can I use Gribouille to create interactive dashboards for the web?

While Gribouille itself generates static PDFs, version 0.3.0 introduces “interactive hints” (tooltips, hyperlinks) that work in PDF viewers and can be exported to HTML via Typst’s --format=html flag, enabling lightweight web dashboards.

How do I import CSV data into a Typst document for Gribouille?

Use Typst’s #let data = csv("path/to/file.csv") to read the file into a table, then reference data inside a #gribouille block just like a data frame in R or pandas.

Is Gribouille compatible with existing Typst templates for business reports?

Yes—Gribouille is a first‑class Typst package, so any template that supports custom packages can embed Gribouille charts using the same #gribouille syntax, preserving margins, headers, and footers.

What are the best practices for version‑controlling Gribouille visualizations?

Keep the data files separate from the .typ source, commit only the source and data snapshots, and use Git tags for each report version. Because the charts are generated from code, you can always reproduce the exact visual by checking out the corresponding commit.

Suggested Code Example

Below is a full Typst snippet that loads a CSV of quarterly sales, applies a corporate theme, and renders a stacked bar chart. Copy‑paste and run to see the instant payoff.

// 1️⃣  Add Gribouille as a dependency (typst.toml)
// [dependencies]
// gribouille = "0.3.0"

#show heading: heading => heading.set(style: "title")

// 2️⃣  Load the data
#let sales = csv("data/quarterly_sales.csv")

// 3️⃣  Define a corporate theme
#let corp-theme = (
  palette: ("#003366", "#006699", "#0099CC"),
  font: "Helvetica",
  background: "#F5F5F5"
)

// 4️⃣  Create the chart
#gribouille(
  data: sales,
  mapping: (x: "Quarter", y: "Revenue", fill: "Region"),
  geom: "bar",
  stat: "identity",
  position: "stack",
  theme: corp-theme,
  title: "Quarterly Revenue by Region",
  xlab: "Quarter",
  ylab: "Revenue (USD M)"
)

Running the above in a Typst file (report.typ) and compiling with typst compile report.typ will produce a PDF where the bar chart updates automatically whenever quarterly_sales.csv is edited.

---

Related reading: Original discussion

What do you think?

Have experience with this topic? Drop your thoughts in the comments - I read every single one and love hearing different perspectives!