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 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.

  • node_color hierarchy:
    • <example-sql-file.sql> overrides schema.yml overrides dbt_project.yml

Note, you need to run or re-run the dbt docs generate command to apply and view the customized colors.

Custom node colors not applicable in dbt Explorer

The custom node_color attribute isn't applicable in dbt Explorer. Instead, Explorer provides lenses, which are map layers for your DAG. Lenses help you better understand your project's contextual metadata at scale and distinguish specific models or subsets of models.

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
Edit this page