MkDocs Integration

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

Installation

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

pip install mkdocs pymdown-extensions dataface

If you prefer the packaged convenience extra, dataface[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: dataface
          class: dataface
          format: !!python/name:dataface.integrations.markdown.fence_dataface
        - name: dataface-example
          class: dataface-example
          format: !!python/name:dataface.integrations.markdown.fence_dataface_example

The handlers resolve file= paths against your project root. Inline examples compile in place.

Usage

Use dataface when you want a render-only embed:

## Revenue Overview

```dataface {file=faces/revenue.yml}
```

Inline YAML also works:

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

Example Layouts

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

```dataface-example {file=docs/docs/charts/examples/bar-charts/minimum.yml}
```

Supported format= options:

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

Example:

```dataface-example {file=examples/charts/all-chart-types.yml format=render-only}
```

Playground Links

dataface-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 Dataface fence handlers resolve either inline YAML or file= input.
3. Dataface compiles and renders the face 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.

Face Rendering API

If you are building another integration, use the face API directly:

from dataface.core.render.face_api import render_face

svg = render_face("faces/overview.yml", format="svg")
html = render_face("faces/overview.yml", format="html")
png = render_face("faces/overview.yml", format="png")  # returns bytes

See the Integrations overview for the broader architecture.