Fun with Markdown in your dashboards

How to use Markdown in your dashboards for fun and profit.

Building effective dashboards often involves providing context for folks to give them insight into how or why a calculation exists. While precise titles, descriptions, and labeled axes can go a long way toward clarifying your visualizations, Metabase also allows you to add flexible text boxes to your dashboards. This post will show you how to take full advantage of this feature using Markdown syntax.

Adding text to dashboards

Select a dashboard you’d like to add text to, and click on the pencil icon to edit the dashboard. Click on the text box button in the dashboard toolbar (shown as Aa). A text box will appear, which you can move around just as you would a question box. To resize the text box, click and drag on its bottom right corner.

<em>Fig. 1</em>. Adding question and text box to dashboard.
Fig. 1. Adding question and text box to dashboard.

Writing in the text box

To interact with a text box, you’ll need to be in edit mode in a dashboard. Click on the pencil icon in the dashboard toolbar in the upper right of the dashboard.

Text boxes in Metabase have two modes.

  • Edit text (pencil icon).
  • Rendered view (eye icon).

The text editor in Metabase employs a lightweight markup language called Markdown. If you’ve never used Markdown before, it takes some getting used to, but you’ll soon learn to appreciate its simplicity. Markdown can make writers feel like coders and coders feel at home.

How Markdown works

You write a line of Markdown:

# Heading

And Metabase converts your plain text into formatted HTML code.


Which renders like this:


You can access six levels of headings just by adding more #s.

# Heading 1
## Heading 2
### Heading 3
#### Heading 4
##### Heading 5
###### Heading 6

Which Metabase renders as:

<em>Fig. 2</em>. Headings as Metabase renders them in a text card on a dashboard.
Fig. 2. Headings as Metabase renders them in a text card on a dashboard.

You can use Markdown syntax to add links, images, gifs, lists, codeblocks, blockquotes, and more. Here’s a text box with heading, paragraph, blockquote, and code block:

<em>Fig. 3</em>. Heading, paragraph, and blockquote.
Fig. 3. Heading, paragraph, and blockquote.

You can do everything this post does and more using text boxes in Metabase. The big deal with Markdown is that you don’t have to write tedious HTML, and Markdown is human-readable even when it’s not rendered. Its minimalist feature set will keep you focused on the content, and provide a standardized look across your dashboards.

You can learn more about Markdown syntax in this guide, as well as from one of Markdown’s original creators, which also includes the philosophy behind Markdown. As a bonus, the site allows you to view its content in Markdown syntax.

Example text box

Here is an example dashboard with a question and text box:

<em>Fig. 4</em>. Dashboard with question and text cards.
Fig. 4. Dashboard with question and text cards.

Here is the Markdown code used in the text box above:

# Analysis

Although `Gadgets` outsold `Gizmos` in 2019, we only introduced `Gizmos`  and `Doohickeys` in September  of 2019. Additionally, both `Gadgets` and `Widgets` were heavily discounted during our spring, summer, and holiday sales.

We expect sales to continue to grow in the `Gizmo` and `Doohickey` product lines.

# SQL query

    sum("PUBLIC"."ORDERS"."QUANTITY") AS "sum"
    WHERE ("PUBLIC"."ORDERS"."CREATED_AT" >= timestamp with time zone '2019-01-01 00:00:00.000Z'
    AND "PUBLIC"."ORDERS"."CREATED_AT" < timestamp with time zone '2020-01-01 00:00:00.000Z')

# Contact

If you have questions, reach out to us on the [\#product](https://fakemessageservice.com/product) channel.

The hypothetical analyst provided some context, code, and contact info: but you can include whatever context will help readers of your report.

Note: in the example above, the analyst pasted the raw SQL query generated by the Notebook Editor for reference. You can view the SQL composed by the Notebook Editor by clicking on the editor icon to “View the SQL” when in editing mode.

You can also use text boxes as simple dividers to keep your dashboards organized.

<em>Fig. 5</em>. Using a text card as a divider to organize your dashboard.
Fig. 5. Using a text card as a divider to organize your dashboard.

One last pro tip for GIF aficionados

The image syntax,

![image description](image-link)

also works for GIFs. Because there are far more important use cases for dashboard text boxes:

<em>Fig. 6</em>. One of these cards is not like the others.
Fig. 6. One of these cards is not like the others.

Happy Markdowning!

Thanks for your feedback!

Get articles like this one in your inbox every month