dbt Docs Markdown Capabilities

dbt docs renders standard Markdown, but the rendering environment has specific capabilities and gaps worth knowing before you invest time in rich documentation.

What Works

The dbt docs site supports the full range of common Markdown syntax:

• Inline formatting: bold, italic, strikethrough
• Headers: all levels (# through ######)
• Lists: ordered and unordered
• Tables: pipe syntax (| col1 | col2 |)
• Code blocks: fenced with triple backticks, with syntax highlighting
• Links: standard Markdown links to external URLs
• Images: standard Markdown image syntax (local and web-hosted)

This applies both to doc blocks in .md files and to inline descriptions in YAML, though YAML descriptions need proper scalar handling (see below).

YAML Scalar Styles

When writing multi-line descriptions directly in YAML (rather than in doc blocks), the scalar style matters:

# Folded (>): collapses line breaks into a single paragraph
description: >
  Customer lifetime value in USD. Calculated using a 3-year rolling
  window with discounted cash flow methodology.

# Literal (|): preserves line breaks exactly
description: |
  Customer lifetime value in USD.
  Calculated using a 3-year rolling window.
  See the LTV methodology doc for details.

The > folded scalar is good for prose descriptions that should render as one paragraph. The | literal scalar is good for multi-line content where formatting matters — bulleted lists, tables, or content with intentional line breaks. For anything beyond a sentence or two, doc blocks are usually cleaner than either YAML scalar style.

Embedding Images

Images work through the asset-paths config in dbt_project.yml:

asset-paths: ["assets"]

Then reference images in doc blocks or descriptions:

![ERD diagram](assets/finance-erd.png)

Web-hosted images work with standard Markdown syntax and external URLs. This is useful for diagrams hosted on Confluence, Notion, or a shared drive.

For ERD generation specifically, dbterd produces diagrams from dbt artifacts in Mermaid, DBML, PlantUML, GraphViz, D2, and DrawDB formats. You can render these as images and embed them in your doc blocks, giving stakeholders a visual map of how models relate to each other.

Cross-Referencing Models

Linking between models within the docs site uses internal URL paths. The format follows the pattern #!/model/model.<project_name>.<model_name>:

description: >
  Filtered based on rules defined in
  [base__stripe__payments](#!/model/model.my_project.base__stripe__payments)

You can find the exact path by navigating to a model in dbt docs serve and copying the URL hash. This is the only way to create internal links in the docs site — the ref() function is not available inside doc blocks.

What Does Not Work

Several commonly requested features are missing from dbt docs:

• Mermaid diagrams: No native rendering support. This is a popular feature request tracked in issue #338 on the dbt-docs repository. You can generate Mermaid diagrams externally and embed them as images instead.
• LaTeX / mathematical notation: No rendering support. If you need formulas, describe them in plain text or embed rendered images.
• Custom pages: There is no way to create documentation pages beyond the auto-generated model/source views and the project overview. The overview page (populated via a doc block named __overview__) is the only customizable top-level page.
• Large file performance: If you have very large .md files (500KB+) containing many doc blocks, dbt’s Jinja parser can hit super-linear slowdowns during compilation. Split large files if you notice compilation time increasing.

How persist_docs Affects Markdown

When you use persist_docs to push descriptions to your warehouse, Markdown formatting gets stripped to plain text. The expanded text of your doc block (not the {{ doc() }} Jinja reference) becomes the warehouse comment, but all Markdown syntax — headers, bold, tables, links — is removed. Write descriptions that read well as plain text if you are using persist_docs, since that is how most consumers will see them.