dbt docs

What Is dbt docs?

dbt docs is a CLI command and static site generator that converts your dbt project's manifest.json into an interactive website. The site visualizes models, sources, tests, and lineage, letting analysts browse dependencies and column-level metadata without reading YAML files.

Why Use dbt docs Instead of a Wiki?

dbt docs stays in sync with your code because the site is rebuilt from the manifest every time you run dbt docs generate. No manual copy-pasting is required, eliminating stale descriptions that plague wikis and spreadsheets.

How Do I Generate Documentation?

Run dbt docs generate from your project root. dbt compiles the project, builds a searchable catalog.json, and writes HTML assets to target/. Commit only the YAML in Git; the site artifacts are usually ignored via .gitignore.

How Do I Serve the Docs Locally?

After generation, run dbt docs serve --port 8080. A local web server starts, and your browser opens to http://localhost:8080, allowing you to click through models, sources, and lineage graphs.

What Metadata Appears in the Site?

The docs site surfaces descriptions, owners, tags, tests, freshness rules, column data types, and lineage. Each node card links to the compiled SQL, making troubleshooting easier for engineers.

How Do I Publish dbt docs in CI/CD?

Use a CI job to run dbt docs generate, then upload target/ to object storage or a static hosting service like S3 + CloudFront, Netlify, or GitHub Pages. Automating this step keeps docs current with every merge to main.

Can I Restrict Access to Sensitive Docs?

Yes. Host the static site behind your SSO provider or VPN. Alternatively, use dbt Cloud's hosted docs with built-in role-based access control and password protection.

How Does dbt docs Handle Model Lineage?

The site renders a DAG graph. Clicking a node highlights upstream and downstream dependencies, helping teams trace data flows and assess blast radius before refactoring.

What Are Best Practices for High-Quality Docs?

Document every model and column in YAML. Use the {{ doc() }} macro to embed rich Markdown. Automate a CI test that fails if descriptions are missing to enforce a documentation culture.

How Does Galaxy Complement dbt docs?

Galaxy's SQL editor fetches dbt manifest metadata to power AI-assisted autocomplete and inline column descriptions. Engineers can jump from a query in Galaxy to the relevant dbt docs page, reducing context switching.

Code Snippet: CI Job for Docs

# .github/workflows/dbt-docs.yml
jobs:
docs:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: duckdb/dbt-action@v1
with:
dbt_command: "dbt deps && dbt seed && dbt run && dbt docs generate"
- uses: netlify/actions/cli@master
with:
args: deploy --dir=target --prod

Real-World Example

At a Series B SaaS firm, adding YAML descriptions and enforcing docs generation in CI reduced onboarding time for new analysts from two weeks to three days because the lineage graph exposed critical model dependencies visually.