Skip to main content

02. Using Docs Blocks

What Are Docs Blocks in dbt?​

Docs blocks are special Markdown blocks inside YAML files that allow you to add rich documentation for your models, sources, or columns.
They are written using the docs() macro in dbt and render as detailed documentation in dbt Docs.


Why Use Docs Blocks?​

Add long-form documentation without cluttering the YAML file
Use Markdown formatting for better readability
Maintain descriptions and details in one place
Generate beautiful, interactive documentation with dbt docs


Basic Syntax of Docs Blocks​

Docs blocks are defined in Markdown files and referenced in YAML files:

Step 1: Create a Docs Block​

Create a file like docs.md inside your models/ folder:

{% docs order_details %}
This model provides **detailed insights** into order data, including:
- Customer information
- Payment details
- Order lifecycle

**Use cases:**
- Reporting dashboards
- Customer analytics
{% enddocs %}

Step 2: Reference the Docs Block in YAML​

Inside your schema.yml:

version: 2

models:
- name: order_details
description: "{{ doc('order_details') }}"
columns:
- name: order_id
description: "Unique identifier for each order"

Benefits of Docs Blocks​

Keep detailed documentation separate from the YAML Use Markdown styling for better formatting Reusability: The same doc block can be referenced in multiple places


Best Practices​

Group related docs in a single file (e.g., docs.md) Use meaningful names for docs blocks ({% docs block_name %}) Keep docs up-to-date with model changes Preview docs with dbt docs generate && dbt docs serve


Example Folder Structure​

models/
│
├── schema.yml
├── docs.md
├── orders.sql
└── customers.sql

=