MkDocs Integration

Embed live dbt charts boards and examples in your MkDocs site with fenced code blocks handled by pymdownx.superfences.

Installation

Install MkDocs, pymdown-extensions, and dbt charts in the same environment:

pip install mkdocs pymdown-extensions dbt-charts

If you prefer the packaged convenience extra, dbt-charts[mkdocs-plugin] still installs the base MkDocs dependency set, but the supported embed path is the fenced markdown handler documented below rather than a separate MkDocs plugin.

Configuration

Register the custom fences in your mkdocs.yml:

markdown_extensions:
  - pymdownx.superfences:
      custom_fences:
        - name: dbt-charts
          class: dbt-charts
          format: !!python/name:dbt_charts.integrations.markdown.fence_dbt_charts
        - name: dbt-charts-example
          class: dbt-charts-example
          format: !!python/name:dbt_charts.integrations.markdown.fence_dbt_charts_example

The handlers resolve file= paths against your project root. Inline YAML and file= inputs are both supported. In dbt charts' published docs, full runnable examples are kept inline so the markdown stays self-contained.

Usage

Use dbt-charts when you want a render-only embed:

## Revenue Overview

    ```dbt-charts {file=charts/revenue.yml}
    ```

Inline YAML also works:

```dbt-charts
charts:
  revenue:
    query: sales
    type: bar
    x: product
    y: revenue
rows:
  - revenue
```

Example Layouts

Use dbt-charts-example when you want the YAML and render together:

    ```dbt-charts-example {file=charts/revenue.yml}
    ```

Supported format= options:

• side-by-side (default)
• stacked
• render-only
• yaml-only

Example:

    ```dbt-charts-example {file=charts/revenue.yml format=render-only}
    ```

Playground Links

dbt-charts-example blocks include playground links automatically. Inline YAML is compressed into the playground URL; file-backed examples use the resolved YAML source.

How It Works

1. MkDocs parses fenced blocks through pymdownx.superfences.
2. The dbt charts fence handlers resolve either inline YAML or file= input.
3. dbt charts compiles and renders the board during the docs build.
4. The rendered output is injected into the generated HTML.
5. Render failures become visible error <div> blocks instead of crashing the entire build.

Board Rendering API

If you are building another integration, open a project session and render directly:

from dbt_charts.agent_api import ProjectSession
from dbt_charts.core.board import raise_on_dashboard_failure

session = ProjectSession.open("path/to/your/project")
try:
    board = session.project.path("charts/overview.yml").read_board()
    rendered = session.render_board(board=board, format="svg")
    raise_on_dashboard_failure(rendered)
    svg = rendered.data  # str for svg/html, bytes for png/pdf
finally:
    session.close()

See the Integrations overview for the broader architecture.