ReadMe

A long standing pain point of mine has been documentation in PowerBI.

When I say this, I don't mean that I hate writing it, I hate that I don't have the ability to convey information in an easy to understand format with basic styling tools that are widely availible in other applications. I'm talking actual rich-text styling, tables, code blocks, linkable indexes, detail dropdowns, embedded images, all with modern styling! Nothing exists on the market that would let me do this... so I made it myself.

The Vision

With the introduction of .pbip files, Power BI now offers source control for reporting. So why not extend that same source control approach to documentation in a format developers are familiar with? Write it in markdown, store it as the README.md in the same repository as the report, set up a connection with your report, and the visual will render the new data source without any additional tinkering. Documentation evolves with the codebase, teams can update documentation without even opening the report, and everything stays in sync. Gone are the days of storing docs in an external SharePoint that atrophy over time.

Setting your data source up is comically simple.

In Power BI Desktop, go to Get Data > Blank Query, open the Advanced Editor, and paste the M code below with your repo details substituted in. When you save, Power BI will prompt for credentials. Select Basic authentication, enter your GitHub username, and paste a Personal Access Token as the password. Apply the credentials to the base https://api.github.com/ URL.

let
    Source = Web.Contents(
        "https://api.github.com/repos/USER/REPO/contents/PATH-TO/README.md",
        [
            Headers=[Accept="application/vnd.github.v3.raw"]
        ]
    ),
    Content = Text.FromBinary(Source),
    Table = #table({"Content"}, {{Content}})
in
    Table

To generate a PAT, go to GitHub Settings > Developer settings > Personal access tokens > Fine-grained tokens. Scope it to the target repository with Contents: Read-only. That is the only permission needed.

Congratulations, you now have a direct line from your report to your repository. Your documentation stands a chance of surviving the test of time.

Features

The visual renders GitHub-flavored markdown directly inside a Power BI report. Everything you would expect from a README.md is supported:

  • Headers (H1 to H6), bold, italic, strikethrough, and underlined text
  • Ordered, unordered, nested, and task lists
  • Tables with column alignment
  • Code blocks with syntax highlighting
  • Blockquotes, including nested
  • Images and linked indexes for in-document navigation
  • Collapsible details/summary sections
  • Footnotes

Font size, padding, background color, and font family are all adjustable through Power BI’s formatting pane. Font size scales proportionally, so headings, paragraphs, and code blocks all stay in sync.

Getting Started

The visual is available on AppSource and can be imported directly from the "Get More Visuals" panel in any report by searching for "ReadMe".

ReadMe