Documents

Documents let you tell a story with your data by combining text, charts, and other content.

Create a document

1. Click the + New button in the top right.
2. Select Document.
3. Do stuff.
4. Click the Save button.

List commands with /

Type / in your document to see available commands:

• Ask Metabot to chat with Metabot in the document.
• Chart to insert a table or chart from an existing question or model. You can’t add dashboards or other documents, but you can mention them (see the next section).
• Link. You can mention other items in your Metabase.

Mention items with @

You can type @ to mention items from your Metabase. (The mentions get a fancy little icon next to them).

Add charts to documents

You can add questions and models to a document.

Adding a chart copies it to the document

When you add a chart from a collection, Metabase creates a copy in the document. The original question remains in the collection. Changes to one copy won’t affect the other; they’re independent.

If however, you delete the document’s copy, that copy is permanently deleted. It can’t be recovered from the trash.

Charts generated by Metabot only exist in the document

If Metabot generates a chart, Metabase saves that question to the document itself. If you delete it, it’s gone forever. You won’t be able to recover the question from the trash.

Editing charts

To edit a chart, click the three-dot menu in the chart’s upper right. You can:

• Edit visualization
• Edit query
• Replace the chart with another question or model

Edits only affect the chart in the document. If you added the chart from a collection, Metabase will have created a copy of the chart. Any changes made to the chart in the document won’t affect the original question.

Arranging charts

To rearrange charts, simply click and hold on the chart and drag it to where you want it in the document.

You can put up to three charts side by side (more than three charts side-by-side gets crowded). To resize charts, you can click on the edges to adjust their size.

When there are multiple charts in the same row, you can resize them horizontally by clicking between the charts and sliding left or right to resize.

To resize a chart’s height, click the bottom of the chart and resize the chart up or down.

For now, you can only put charts side-by-side (not text elements).

After arranging your charts, save your changes!

Formatting text

Documents support Markdown syntax for:

• Headings: #
• Images: Use Markdown image syntax: ![Image text](image link). The image must start its own line in the document, and you may need to type out the closing parenthesis to let Metabase know to render the image. The image link must be a valid URL that your Metabase can access.
• Blockquotes: > This is a blockquote.
• Code blocks: Wrap with triple backticks (```). Syntax highlighting isn’t supported yet.

You can also access formatting options by typing /.

Links

If you paste a link into a document, Metabase will turn it into a clickable link. For now, Markdown links aren’t supported, and you can’t change the link text.

Commenting on documents

To comment on a text element, click the chat bubble next to the section. You can only comment on whole sections; you can’t highlight text to comment on.

To comment on a chart:

1. Hover over the chart.
2. Click the three-dot menu.
3. Select Comment.

You can:

• React to comments with emojis (which are like pictures masquerading as words). For example, this is a gondola: 🚠.
• Mention other items or people in your Metabase (type @ and then search for who/what you want to mention).
• Link to a comment. Click the three-dot menu and select Copy link.
• Resolve comments. Resolved comments appear in a separate tab.

Comment notifications

If someone mentions you in a thread, or responds to a comment in a thread you’re in, Metabase will send you an email to let you know.

Currently, there’s no central place to view all of your threads and mentions, and no way to disable email notifications for comments.

Deleting comments

If you never want to see a comment again:

1. Resolve the comment.
2. Find it in the Resolved tab.
3. Click on the three-dot menu.
4. Select Delete.

This deletion is permanent.

Printing documents

To print a document, click on the three-dot menu and select Print document.

When to use a document vs. a dashboard

Documents and dashboards both have their use cases.

Prefer documents for exploration and narration

Documents work best for:

• Telling a story with data
• Opening analysis for comments
• Exploratory analysis

Use dashboards for tracking metrics

Dashboards work best for:

• Regular analysis. Numbers you want to keep an eye on every day, week, or month.
• Filtering results across multiple charts.
• More control over presentation.

Document permissions

Whether someone can view or edit a document and its data depends on that person’s collection and data permissions. See Permissions.