dbt docs generate and serve

TL;DR

Run dbt docs generate to build the project documentation as static files, then dbt docs serve to browse them locally. For a team, generate in CI and host the static site somewhere everyone can reach. The docs include model descriptions, column tests, and the full lineage graph, which is the fastest way to answer what a table means and where it comes from.

The query

dbt docs generate and serve

Use this when

• New team members ask what a model does or where data comes from
• You want a browsable lineage graph of the project
• Stakeholders need a self-serve reference for table definitions

Not for

• Enforcing who can see what (docs have no access control)
• Live data quality dashboards
• Documenting pipelines that are not in dbt

Steps

1. Add descriptions to your models and columns in the schema YAML. Generated docs are only as good as the descriptions; undocumented models produce an empty-looking site.

Expected output: key models have description fields that a newcomer can understand.

1. Generate the docs artifacts:

dbt docs generate

Expected output: target/catalog.json, target/manifest.json, and target/index.html appear in the project.

1. Serve locally to preview:

dbt docs serve --port 8080

Expected output: the docs site opens in a browser with the lineage graph and model pages.

1. Host it for the team. Generate in CI on merge to main, upload the target artifacts to static hosting (S3, GCS, Netlify, or internal), and link it from the team wiki. Refresh on every merge so docs never go stale.

Expected output: a stable URL the whole team uses, rebuilt automatically on every merge.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_HFScAlLUg85Kl7vbtu5Qlg