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
=