# Markdown documentation > Write Markdown docs with YAML frontmatter and link them to your models, datasets, and dashboards, so analytics context lives next to the analytics it describes. :::info 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 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 `.md` file 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.aml` file, 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: ```markdown --- 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](/docs/development/aml-studio). ## Related - [Development Workspace](/docs/development/aml-studio) - where you author AML and Markdown files. - [Project Structure](/docs/development/project) - how files are organised in a project.