Skip to main content

Markdown for analytics context

Coming soon

Markdown as a first-class documentation object is on the way. This page previews what it will do; we'll update it when the feature ships.

Overview​

Markdown documentation keeps business context inside the project, next to the analytics it explains. Write an ordinary .md file in the Development workspace, and it becomes part of your analytics rather than a separate note.

It is most useful when you need to:

  • Share business context: define what a metric means, includes, and excludes.
  • Record modeling decisions: explain why a model or field works the way it does.
  • Onboard new team members: provide a written guide to the datasets and context they need.
  • Give AI agents approved context: provide the same documented context analysts use.

Key capabilities​

The feature includes the following key capabilities:

  • Frontmatter as structured metadata: a --- fenced YAML block at the top of a file renders as a readable Properties panel instead of raw text. No schema is enforced, so you choose the fields that fit your team.

    Properties panel rendered from YAML frontmatter, with the tags field highlighted showing ecommerce, runbook, orientation and on-call tags

  • Link to another document: a standard Markdown link pointed at another .md file resolves and is clickable.

    A Markdown table with its Read column highlighted, showing resolved links to other documents in the project

  • Link to a model, dataset, or dashboard: the same syntax works against a .model.aml, .dataset.aml, or .page.aml file, and resolves with a hover card.

    Properties panel with the related_dataset and related_dashboard values highlighted, resolved to the Ecommerce Dataset and Ecommerce Dashboard

  • Preview AML source inline: Ctrl+hover a resolved AML link to read its highlighted source without leaving the document, useful for confirming a metric's exact formula from the prose that references it.

    Highlighted popover showing the AML source of ecommerce.dataset.aml while the cursor rests on the Ecommerce Dataset link beneath it

How it works​

Frontmatter​

Add a --- fenced YAML block at the top of any .md file. Holistics parses it and renders the fields as properties.

---
doc_type: dashboard_context
audience: business_users
related_dataset: Ecommerce Dataset
related_models:
  - users
  - orders
---

No frontmatter schema is enforced. Holistics displays any valid YAML you write, so teams converge on their own field conventions (commonly an owner, a status, a document type, and a list of related objects).

Use a standard Markdown link with a root-relative path. The same syntax covers .md documents and AML objects.

Start with the [glossary](/docs/glossary.md) for metric definitions.

Revenue is modelled in [Ecommerce Dataset](/datasets/ecommerce.dataset.aml),
which builds on [orders](/models/orders.model.aml).

Encode spaces in a file name: [Sales Report](/reporting/Sales%20Report.page.aml).
  • A resolved AML link carries a hover card, and Ctrl+hover expands it into the file's highlighted source.
  • Links resolve to whole files, not to a single metric or report. To reference a metric, link to the dataset file that defines it.
  • A path that matches no file in the project renders as "File not found."

Markdown documentation will be available in the Development workspace.

Open Markdown
Let us know what you think about this document :)