Markdown¶

Write a charts fence in a Markdown page and the site build draws it as a chart. dbt Charts ships a Python-Markdown extension, so it works in any site built on Python-Markdown: MkDocs and Pelican are set up below. For a site generator that doesn't run Python-Markdown (Hugo, Jekyll, Astro, Docusaurus, GitHub READMEs), see Static sites.

Installation¶

Install dbt Charts in the same environment as your site generator:

pip install dbt-charts

Configuration¶

Add dbt_charts.integrations.markdown to the Markdown extensions your site generator passes to Python-Markdown.

MkDocs¶

Add one line to mkdocs.yml:

markdown_extensions:
  - dbt_charts.integrations.markdown

Pelican¶

Add it to MARKDOWN in pelicanconf.py, beside Pelican's default extensions:

MARKDOWN = {
    "extension_configs": {
        "markdown.extensions.codehilite": {"css_class": "highlight"},
        "markdown.extensions.extra": {},
        "markdown.extensions.meta": {},
        "dbt_charts.integrations.markdown": {},
    },
    "output_format": "html5",
}

Python-Markdown¶

Pass it by name like any other extension:

import markdown

html = markdown.markdown(text, extensions=["dbt_charts.integrations.markdown"])

Usage¶

A fence holds what one item of a board's rows: holds: a chart, a whole board, or the name of a chart or board file. It means the same thing here as in a markdown board:

Revenue kept climbing through the spring.

```charts
type: line
title: Revenue by month
query:
  columns: [month, revenue]
  values:
    - [Jan, 100]
    - [Feb, 150]
    - [Mar, 200]
x: month
y: revenue
```

Query and chart names are shared across the page, so one fence can use a query another fence declares. Each fence is drawn as its own chart, in its place in the prose.

To show a fence as code instead, wrap it in a longer fence, or use a different language tag.

A charts-example fence draws a whole board beside its YAML, with a link that opens it in the Playground. Add {format=stacked}, {format=render-only}, {format=yaml-only} or {format=tab} to change the layout, or {file=charts/revenue.yml} to read the board from a file. tab draws the board with its YAML folded into a "See the YAML" tab under it. A page that shows what a failed query looks like adds {allow-chart-errors=true}, the fence's version of dct render --allow-chart-errors.

A page with a charts-example fence carries the stylesheet for these layouts, once, so they look the same on any theme. Its classes all start with dbt-charts-, so they stay clear of your theme's own. It comes after your theme's CSS, so a rule of your own that restyles one needs a more specific selector.

Hover and tooltips¶

Charts drawn from fences show tooltips and hover emphasis, because the extension puts the hover script in each page that draws a chart, once however many charts the page holds. Charts on one page may use different themes: each shows its own tooltip. A chart added to the page after it loads, by a script that swaps HTML in, works too.

Hover works for inline SVG only. An SVG embedded with an <img> tag can't run scripts, so it draws the chart without hover.

A site that would rather serve the script itself, once and cached, turns the option off and writes the file with dct runtime-js. A site whose Content Security Policy forbids inline scripts must do the same, since the browser won't run the copy in the page:

dct runtime-js --out docs/javascripts/charts.js

markdown_extensions:
  - dbt_charts.integrations.markdown:
      include_runtime: false
extra_javascript:
  - javascripts/charts.js

Data and project¶

A chart with inline columns: and values: needs no project. To query a warehouse, build the site from inside a dbt Charts project: the extension uses the nearest dbt_charts.yml above the directory you build from (else the git root, else that directory itself), and the build needs that project's credentials. A file path in a fence is read from the project's charts/ folder, and charts/meta.yml applies to every page.

Query results are cached as in dct render, so a rebuild inside a query's cache: duration does not query the warehouse again. The extension finds the cache file as dct does: DCT_CACHE_PATH if set, else the path in the project's cache: block in dbt_charts.yml, else the per-user file; --no-cache belongs to the dct command alone. For a CI build to keep its results between runs, point the cache into a directory of its own, such as .cache/charts.duckdb, and save that whole directory: the cache can hold recent results in a file beside the one you named.

Option	Default	Meaning
`project_dir`	nearest project	The dbt Charts project the charts read from
`embed_fonts`	`true`	Carry the fonts in each page, each face once. Turn it off only if your site serves the font files at `/static/fonts/`
`include_runtime`	`true`	Carry the hover script in each page that draws a chart. Turn it off if your site serves the script itself (see Hover and tooltips)
`variables`	none	Values for variables, by name, as a link's query parameters would set them. They apply to every page with a chart, and each such page must declare them; a variable left out takes its `default:`

Each chart carries a small "made with dbt Charts" footer. To turn it off, set style.footer.visible: false in charts/meta.yml.

Errors¶

A fence that fails to render stops the build, with the error and the line of the fence. A broken chart never ships as a page.