Skip to content
← Back to Blog

2026-03-31 9 min read

Markdown and Mermaid Diagrams in Power BI — A Practical Guide

An overview of features, setup, and use cases for the free Markdown / Mermaid Renderer visual for Power BI.

published on 2026-03-31


Power BI is an excellent tool for data visualisation. What is often missing is a simple way to display formatted text, explanations, or process diagrams directly within a report. That is exactly what the Markdown / Mermaid Renderer is for — a free, open-source custom visual that renders Markdown content including Mermaid diagrams directly in Power BI.

In this article, I will show how to set up the visual, what features it offers, and which use cases it is particularly well suited for.


What Is the Markdown / Mermaid Renderer?

The visual takes Markdown text from a column or measure and renders it as formatted content — headings, lists, tables, code blocks, and of course Mermaid diagrams. Everything happens locally in the browser, with no external network calls.

flowchart LR
    A["Column or Measure (Markdown Text)"] --> B["Markdown / Mermaid Renderer Visual"]
    B --> C["Formatted Content + Diagrams"]

The visual is available under the MIT licence and can be used freely for commercial and personal purposes.


Setup

Installation

There are two ways to install the visual:

  1. AppSource: In Power BI Desktop, go to Get more visuals and search for "Markdown Mermaid Renderer".
  2. Manual: Download the .pbiviz file from GitHub and import it via Import a visual from a file.

Getting Started

  1. Place the visual on your report page
  2. Drag a column or measure containing Markdown text into the "Markdown Content" field
  3. The content is rendered immediately

A simple example measure to try out:

Project Overview =
"# Project Alpha

**Status:** On Track  
**Owner:** Sarah M.

## Current Sprint

- Finalise data model
- Review KPI definitions
- Prepare deployment"

This is then rendered as follows:

Project Alpha

Status: On Track
Owner: Sarah M.

Current Sprint

  • Finalise data model
  • Review KPI definitions
  • Prepare deployment

The measure is displayed as a formatted document — with headings, bold text, and bullet points.


Mermaid Diagrams: Creating Diagrams from Text

What makes the visual particularly useful is its support for Mermaid. Mermaid is a text-based diagramming language: you describe a diagram in code, and it is rendered as an SVG. No drawing tool, no static screenshot that goes out of date.

An example — a simple flowchart:

```mermaid
flowchart LR
    Sources["Data Sources"] --> ETL["ETL / Dataflows"]
    ETL --> Model["Semantic Model"]
    Model --> Reports["Reports & Dashboards"]
```

This is rendered directly in the Power BI report as an interactive SVG diagram like this:

flowchart LR
    Sources["Data Sources"] --> ETL["ETL / Dataflows"]
    ETL --> Model["Semantic Model"]
    Model --> Reports["Reports & Dashboards"]

Supported Diagram Types

Mermaid supports a wide range of diagram types, all of which work in the visual:

mindmap
  root((Mermaid Diagrams))
    Processes
      Flowcharts
      Sequence Diagrams
    Data Architecture
      ER Diagrams
      Class Diagrams
    Planning
      Gantt Charts
      Quadrant Charts
    Communication
      Pie Charts
      Timelines

Multiple Measures in One Visual

Instead of a single measure, up to 10 measures can be added to the visual at the same time. Each measure is rendered as its own section. This allows many elements to be presented together in a structured way, rather than placing each element in its own visual (which often does not result in a clean design).

flowchart LR
    M1["Revenue"] --> V["Markdown Visual"]
    M2["Growth Rate"] --> V
    M3["Top Products"] --> V
    V --> R["Structured Report Section"]

Per-Measure Formatting

Once two or more measures are present, the "Measure formatting" section appears in the property pane. There, a formatting function can be selected for each measure:

Format Effect Example
None No formatting (default) Value is rendered directly
Heading (H1–H3) Wraps the value as a heading ## Value
Code Block Displayed as a code block ```dax ... ```
Definition List Measure name as label, value as definition Revenue / : €1,234,567
Blockquote Displayed as a blockquote > Value
Unordered / Ordered List Value is split by delimiter - Item 1 / - Item 2

Definition Lists for KPIs

The Definition List format is particularly well suited for KPI displays. The measure's display name is automatically used as the label, the value as the definition:

Monthly Active Users
: 14,832

Revenue Q1
: €1,234,567

No string concatenation in DAX is needed — the visual handles the formatting. The measure's display name in the data model controls the label.

Lists from CONCATENATEX

The list formats are especially useful in combination with CONCATENATEX():

Top Products =
    CONCATENATEX(
        TOPN(3, Products, Products[Revenue], DESC),
        Products[ProductName],
        ", "
    )

With the Ordered List format and the delimiter , , this becomes:

Top Products

  1. Widget A
  2. Gadget B
  3. Module C

The delimiter and heading level are configurable in the property pane.


DAX and Power Query Syntax Highlighting

Code blocks with the language identifiers dax, powerquery, pq, or mscript are displayed with syntax highlighting:

```dax
Total Sales =
VAR _sales = SUMX(Sales, Sales[Quantity] * Sales[UnitPrice])
RETURN
    IF(_sales > 0, _sales, BLANK())
```
```powerquery
let
    Source = Sql.Database("server", "db"),
    Filtered = Table.SelectRows(Source, each [Status] = "Active")
in
    Filtered
```

This is particularly helpful when DAX expressions or M scripts need to be presented as part of the documentation within the report.


Display Options

Dark / Light Mode

The colour mode can be toggled in the property pane. Markdown content, Mermaid diagrams, and all UI elements adapt automatically.

Fonts

Font family, heading size, body text size, and Mermaid font size can be configured independently.

Search

Via the "Use search bar" setting in the View Settings, a search bar is displayed. Use Ctrl+F to search across all rendered content — helpful for longer documentation.

Fullscreen Mode for Diagrams

Every Mermaid diagram has a fullscreen button (⛶). This is useful for complex diagrams that need to be examined in detail. Zoom and pan are available in fullscreen mode.

Copy Markdown Menu

When "Copy markdown menu" is enabled, the right-click menu offers Copy section markdown and Copy all markdown to copy the raw text to the clipboard.


Cross-Filtering: Documentation Meets Interactivity

When a column (rather than a single measure) is used as the data source, each row is rendered as its own section. With Cross filter enabled:

  • Clicking a section filters other visuals based on the corresponding data row
  • Ctrl+Click for multi-selection
  • Non-selected sections are dimmed

This enables a pattern where, for example, process descriptions or product documentation serve as clickable sections that simultaneously filter the remaining report visuals.


Practical Example: Automatic Measure Documentation

A concrete use case that can be set up in just a few minutes: automatic documentation of all measures in the data model.

Power BI Desktop (from April 2024) provides the INFO.VIEW.MEASURES() function, which returns metadata for all measures. Combined with CONCATENATEX() and some Markdown formatting, this produces a measure that generates a complete, searchable documentation of all measures.

flowchart LR
    A["INFO.VIEW.MEASURES()"] -->|Measure Metadata| B["CONCATENATEX + Markdown"]
    B --> C["Single DAX Measure"]
    C --> D["Markdown Visual"]
    D --> E["Searchable Measure Documentation"]

The DAX Query

Paste the following into DAX Query View and execute. Replace 'Measure' with an existing table name in your model:

DEFINE

    FUNCTION CodeFence =
        ( CodeContent : STRING VAL, CodeLanguage : STRING VAL) =>
        VAR _fence = "` ` `"
        VAR _nl = UNICHAR ( 10 )
        RETURN
            IF (
                ISBLANK ( CodeContent ),
                "",
                _fence & CodeLanguage & _nl
                    & CodeContent & _nl & _fence
            )

    MEASURE 'Measure'[Measure Documentation] =
        VAR _nl = UNICHAR ( 10 )
        VAR _nl2 = _nl & _nl
        VAR _measures = INFO.VIEW.MEASURES ()
        VAR _result =
            CONCATENATEX (
                _measures,
                VAR _header = "## " & [Name]
                VAR _blockquote =
                    "> "
                        & IF (
                            ISBLANK ( [Description] ),
                            "_no description present_",
                            [Description]
                        )
                VAR _list =
                    "- Table : " & [Table] & _nl
                        & "- Display Folder : "
                        & IF (
                            ISBLANK ( [DisplayFolder] ),
                            "–", [DisplayFolder]
                        ) & _nl
                        & "- Data Type : " & [DataType] & _nl
                        & "- Is Hidden : "
                        & IF ( [IsHidden], "True", "False" )
                VAR _exprHeading = "### Expression"
                VAR _exprBlock =
                    CodeFence ( [Expression], "dax" )
                VAR _formatHeading = "### Format String"
                VAR _formatBlock =
                    CodeFence (
                        [FormatStringDefinition], "dax"
                    )
                RETURN
                    _header & _nl2
                        & _blockquote & _nl2
                        & _list & _nl2
                        & _exprHeading & _nl2
                        & _exprBlock
                        & IF (
                            NOT ISBLANK (
                                [FormatStringDefinition]
                            ),
                            _nl2 & _formatHeading & _nl2
                                & _formatBlock,
                            ""
                        ),
                _nl2 & "---" & _nl2,
                [Name], ASC
            )
        RETURN
            _result

EVALUATE
{ [Measure Documentation] }

After execution, right-click the measure definition and select "Add to model" to add it to your data model. Then place the Markdown visual on a report page, drag the measure into the Markdown Content field, and enable the search bar.

The result: an always up-to-date, searchable documentation of all measures — directly within the Power BI report.


Tips for Getting Started

  • Load the sample report: The GitHub repository contains a ready-made .pbix report in the pbi_example/ folder with various diagram types and formatting options.
  • Use the Mermaid Live Editor: At mermaid.live, diagrams can be tested before inserting them into Power BI.
  • Enable the search bar: Especially for longer documentation, the built-in Ctrl+F search saves a lot of time.

Connection to fennibi.com

The Markdown / Mermaid Renderer visual was created as part of fennibi.com — an automated documentation solution for Power BI Semantic Models. Fennibi generates structured Markdown documentation with Mermaid diagrams for relationships, lineage, and architecture, which is then displayed directly in the Power BI report via this visual.

However, the visual works independently of Fennibi with any Markdown text source — whether from a DAX measure, a SharePoint list, or a manually maintained documentation table.


Summary

Property Details
Licence MIT — free for any use
Installation AppSource or manual .pbiviz file
Markdown Rendering Headings, lists, tables, code blocks, bold, italic
Mermaid Diagrams Flowcharts, sequence, ER, class, Gantt diagrams and more
Syntax Highlighting DAX, Power Query (M), and other languages
Formatting Options Definition lists, lists, code blocks, headings per measure
Interactivity Cross-filtering, zoom/pan, fullscreen, search
Theming Dark/light mode, configurable fonts, theme file support
Security No external network calls, DOM sanitisation
Source Code github.com/pmoldmann/mermaid-powerbi

💬 Join the Discussion

Have questions, ideas, or feedback about the Mermaid Power BI Visual? I'd love to hear from you — feel free to leave a comment on the LinkedIn post for this article.