Markdown documentation
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
Every .md file in your project (business definitions, modeling decisions, onboarding guides) will become a first-class documentation object. YAML frontmatter at the top of a file will render as a structured Properties panel, and standard Markdown links will resolve to the models, datasets, and dashboards the document describes.
Today, Markdown files behave like standalone text: frontmatter shows as raw characters, and nothing connects a document to the analytics it explains. Markdown documentation puts the reasoning behind a model, or the assumptions behind a metric, next to the file it applies to instead of in a pull request thread or a separate wiki.
Key capabilities
Markdown documentation integrates seamlessly with your existing analytics files to provide context directly where it is needed. 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. - Link to another document: a standard Markdown link pointed at another
.mdfile resolves and is clickable, connecting related documentation. - Link to a model, dataset, or dashboard: the same syntax works against a
.model.aml,.dataset.aml, or.page.amlfile, and resolves with a hover card. - 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.
How it works
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).
Links use standard Markdown syntax against a root-relative path to the target file, with spaces encoded as %20. A link to datasets/ecommerce.dataset.aml resolves to that dataset with a hover card. If the path does not match a file in the project, the link renders as "File not found."
Links resolve to whole files. To reference a metric, link to the dataset file that defines it. There is no dedicated link target for a single metric or report.
Markdown documentation will be available in the Development workspace.
Related
- Development Workspace - where you author AML and Markdown files.
- Project Structure - how files are organised in a project.