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 Explorer

The custom node_color attribute isn't applicable in dbt Explorer. Instead, Explorer provides lenses, which are map layers for your DAGA DAG is a Directed Acyclic Graph, a type of graph whose nodes are directionally related to each other and don’t form a directional closed loop.. 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