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 YAML and file= inputs are both supported. In Dataface's published docs, full runnable examples are kept inline so the markdown stays self-contained.

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=faces/revenue.yml}
    ```

Supported format= options:

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

Example:

    ```dataface-example {file=faces/revenue.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, open a project session and render directly:

from dataface.agent_api import ProjectSession
from dataface.core.dashboard import raise_on_dashboard_failure

session = ProjectSession.open("path/to/your/project")
try:
    face = session.project.path("faces/overview.yml").read_face()
    rendered = session.render_dashboard(face=face, 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.