dbt Docs Site Customization Options

The default dbt docs site supports a limited set of customizations. This note covers the available options and where they end.

The __overview__ doc block

By default, the docs site landing page shows generic boilerplate. It can be replaced with a doc block named __overview__:

{% docs __overview__ %}
# Data platform documentation

Welcome to the analytics engineering documentation for [your company].

**Quick links:**
- Mart models are in the `models/marts/` directory
- Source definitions are under `models/base/`
- Questions? Reach us at #data-team in Slack

Last updated: see the pipeline run history for freshness info.
{% enddocs %}

This doc block goes in any .md file within the project’s resource paths. The overview page orients team members: where to find things, who to ask, what conventions the project follows. It supports full Markdown — headers, links, tables, code blocks, images.

DAG node colors

You can color nodes in the lineage graph by setting docs.node_color in dbt_project.yml or per model. Any hex color or named CSS color works:

models:
  my_project:
    base:
      +docs:
        node_color: "#a3c4bc"
    marts:
      +docs:
        node_color: "#c49a6c"

This helps visually distinguish layers in the DAG. Common patterns:

• Color by layer: base models in one color, intermediate in another, marts in a third. Immediately communicates the transformation stage.
• Color by team: models owned by the finance team in blue, marketing in green, product in orange. Useful for projects with multiple contributing teams.
• Color by domain: revenue models in one color, customer models in another. Helps stakeholders find their area of the graph.

Per-model overrides work too, for cases where a specific model needs to stand out:

models:
  - name: mrt__finance__revenue
    config:
      docs:
        node_color: "#ff6b6b"

Hiding models from documentation

Models that would clutter the DAG without adding value to readers can be hidden with docs.show: false:

models:
  - name: int__order_items_pivoted
    config:
      docs:
        show: false

Good candidates for hiding:

• Intermediate models that exist only as transformation steps and are never queried directly
• Utility models like date spines or mapping tables that add noise to the lineage graph
• Internal staging models that mirror sources but add no business logic

Hidden models are excluded from both the model list and the DAG visualization. Their upstream and downstream connections are also removed from the graph, so hiding a middle node effectively disconnects its parent from its children in the visual representation. Use this deliberately.

You can also apply this at the directory level:

models:
  my_project:
    intermediate:
      +docs:
        show: false

Where the customization options end

That is roughly the boundary. The default dbt docs site offers no official way to:

• Add custom CSS or change the visual theme
• Change the page title from “dbt Docs”
• Add your company logo or branding
• Create custom navigation or additional pages
• Add custom JavaScript or analytics tracking
• Modify the DAG layout algorithm

Open issues on the dbt-docs repository have requested white-labeling and theming support for years. The only workaround is post-processing the generated HTML — injecting CSS, replacing the title tag, adding a logo image. This breaks every time docs are regenerated and requires a build step to patch the output. For deeper customization needs, Alternatives to Default dbt Docs covers the options, from Dagster’s Next.js replacement to full data catalog platforms.