ServicesAboutNotesContact Get in touch →
EN FR
Note

dbt Docs Customization and Deployment

A reading path through customizing and deploying dbt docs beyond localhost — from understanding the build artifacts to choosing a hosting platform, automating deployment, and knowing when to replace the default frontend

Planted
dbtdata engineering

This hub covers deploying dbt docs beyond localhost — from understanding what dbt docs generate produces to choosing a hosting platform, automating deployment, and deciding when to replace the default site entirely.

Prerequisites

  • A dbt project (Core or Cloud) with models
  • Familiarity with dbt docs generate and dbt docs serve
  • For hosting notes: access to at least one of GitHub, GCP, AWS, or a container runtime

Reading Order

The notes follow the natural progression of deploying dbt documentation:

  1. dbt Docs Generate Artifacts — Start here. Understand what dbt docs generate actually produces: the three output files, the flags that control generation (--static, --select, --no-compile), and why dbt docs serve is a preview tool, not a deployment strategy.

  2. dbt Docs Site Customization Options — Before deploying, make the site worth visiting. The __overview__ doc block, DAG node colors, and hiding clutter models are the three customizations available. This note also covers where the customization options end, which is sooner than you might expect.

  3. dbt Docs Performance at Scale — The default frontend is an AngularJS 1.x SPA that parses everything client-side. For small projects this is fine. For large ones (500+ models), it becomes a real problem. Understand the performance ceiling before investing in hosting.

  4. Hosting dbt Docs Beyond Localhost — The reference guide to deployment options: GitHub Pages, Netlify, GCS with IAP, S3 with CloudFront, and Docker with Nginx. Organized by complexity, with authentication considerations for each.

  5. Automating dbt Docs Deployment — CI/CD workflows for GitHub Actions and GitLab CI, Astronomer Cosmos operators for Airflow, and patterns for pushing docs to non-technical platforms like Notion.

  6. Alternatives to Default dbt Docs — When customization and hosting optimizations cannot fix the underlying limitations. Dagster’s Next.js replacement frontend, dbterd for ERD generation, data catalogs, and dbt Cloud Catalog. Includes a decision framework for choosing between them.

For the content side of dbt documentation (what to write, not where to host it), see the AI-powered documentation hub, doc blocks, and Markdown capabilities. For pushing descriptions into the warehouse instead of (or alongside) the docs site, see persist_docs.