Skip to main content

docs

You can configure docs behavior for many resources at once by setting in dbt_project.yml. You can also use the docs config in properties.yaml files, to set or override documentation behaviors for specific resources:

dbt_project.yml
models:
<resource-path>:
+docs:
show: true | false
node_color: color_id # Use name (such as node_color: purple) or hex code with quotes (such as node_color: "#cd7f32")

models/schema.yml
version: 2

models:
- name: model_name
docs:
show: true | false
node_color: color_id # Use name (such as node_color: purple) or hex code with quotes (such as node_color: "#cd7f32")

Definition

The docs property can be used to provide documentation-specific configuration to models. It supports the attribute show, which controls whether or not nodes are shown in the auto-generated documentation website. It also supports node_color for models, seeds, snapshots, and analyses. Other node types are not supported.

Note: Hidden models will still appear in the dbt DAG visualization but will be identified as "hidden.”

Default

The default value for show is true.

Examples

Mark a model as hidden

models:
- name: sessions__tmp
docs:
show: false

Mark a subfolder of models as hidden

Note: This can also hide dbt packages.

dbt_project.yml
models:
# hiding models within the staging subfolder
tpch:
staging:
+materialized: view
+docs:
show: false

# hiding a dbt package
dbt_artifacts:
+docs:
show: false

Custom node colors

The docs attribute now supports node_color to customize the display color of some node types in the DAG within dbt docs. You can define node colors in the following files and apply overrides where needed. Note, you need to run or re-run the command dbt docs generate.

node_color hierarchy:

<example-sql-file.sql> overrides schema.yml overrides dbt_project.yml

Examples

Add custom node_colors to models that support it within subdirectories based on hex codes or a plain color name.

Example

marts/core/fct_orders.sql with node_color: red overrides dbt_project.yml with node_color: gold

marts/core/schema.yml with node_color: #000000 overrides dbt_project.yml with node_color: gold

dbt_project.yml
models:
tpch:
staging:
+materialized: view
+docs:
node_color: "#cd7f32"

marts:
core:
materialized: table
+docs:
node_color: "gold"
marts/core/schema.yml
models:
- name: dim_customers
description: Customer dimensions table
docs:
node_color: '#000000'
marts/core/fct_orders.sql
{{
config(
materialized = 'view',
tags=['finance'],
docs={'node_color': 'red'}
)
}}

with orders as (

select * from {{ ref('stg_tpch_orders') }}

),
order_item as (

select * from {{ ref('order_items') }}

),
order_item_summary as (

select
order_key,
sum(gross_item_sales_amount) as gross_item_sales_amount,
sum(item_discount_amount) as item_discount_amount,
sum(item_tax_amount) as item_tax_amount,
sum(net_item_sales_amount) as net_item_sales_amount
from order_item
group by
1
),
final as (

select

orders.order_key,
orders.order_date,
orders.customer_key,
orders.status_code,
orders.priority_code,
orders.clerk_name,
orders.ship_priority,

1 as order_count,
order_item_summary.gross_item_sales_amount,
order_item_summary.item_discount_amount,
order_item_summary.item_tax_amount,
order_item_summary.net_item_sales_amount
from
orders
inner join order_item_summary
on orders.order_key = order_item_summary.order_key
)
select
*
from
final

order by
order_date

If a node_color is incompatible with dbt docs, you will see a compile error, as in the example below.

Invalid color name for docs.node_color: aweioohafio23f. It is neither a valid HTML color name nor a valid HEX code.
dbt_project.yml
models:
tpch:
marts:
core:
materialized: table
+docs:
node_color: "aweioohafio23f"
0