dbt Generating Docs Site

dbt can produce a full documentation website from your project files with two commands. The site includes model descriptions, column definitions, test results, source freshness status, and an interactive lineage graph. This topic explains what each command does, what files it produces, and how to share the documentation site with your team.

The Two Commands

dbt docs generate   ← creates JSON files with all documentation data
dbt docs serve      ← starts a local web server and opens the browser

dbt docs generate

This command reads your project — all YAML files, SQL files, and the run results in target/manifest.json — and writes a file called target/catalog.json.

$ dbt docs generate

Running with dbt=1.8.3
Building catalog
Catalog written to /my_project/target/catalog.json

What catalog.json Contains

The catalog.json file describes every database object dbt manages: tables, views, sources, seeds, and snapshots. For each object it records the column names, data types, row counts, and byte sizes retrieved directly from the warehouse's information schema. This is why you must run dbt run before dbt docs generate — the warehouse objects must exist for dbt to inspect them.

Files That Power the Docs Site

target/
  manifest.json     ← all model definitions, descriptions, tests, DAG
  catalog.json      ← column types and row counts from the warehouse
  index.html        ← the documentation website (single HTML file)
  graph.gpickle     ← DAG graph data

The index.html file is the entire documentation website in one file. It loads the JSON data and renders everything in the browser. You can host this single file anywhere.

dbt docs serve

This command starts a lightweight web server on your computer and opens the documentation site in your default browser:

$ dbt docs serve

Running with dbt=1.8.3
Serving docs at http://localhost:8080
Press Ctrl+C to stop the server

Changing the Port

dbt docs serve --port 8888
# Opens at http://localhost:8888

Navigating the Documentation Site

The Overview Page

The landing page shows a project summary with model count, source count, test count, and a lineage graph of the entire project.

The Sidebar

The left sidebar lists all nodes organized by type:

• Models (grouped by folder)
• Sources
• Seeds
• Snapshots
• Exposures

The Model Page

Click any model in the sidebar to see:

• The model's description
• The raw SQL code and compiled SQL
• All columns with names, types, and descriptions
• Tests applied to each column
• A mini lineage graph showing direct parents and children

The Lineage Graph

Click the graph icon in any model's page to open the full lineage view. Use the filter controls to:

• Expand upstream (show parents, grandparents)
• Expand downstream (show children, grandchildren)
• Filter by resource type (models, sources, seeds)

Hosting the Docs Site for Your Team

The three files needed to host the documentation site are index.html, manifest.json, and catalog.json. Copy them to any static hosting service:

Option 1: S3 + CloudFront (AWS)

aws s3 sync target/ s3://my-company-dbt-docs/ \
    --include "index.html" \
    --include "manifest.json" \
    --include "catalog.json"

Option 2: GitHub Pages

# Copy docs files to gh-pages branch
cp target/index.html docs/
cp target/manifest.json docs/
cp target/catalog.json docs/
git add docs/
git commit -m "Update dbt docs"
git push origin gh-pages

Option 3: dbt Cloud (Automatic)

dbt Cloud generates and publishes documentation automatically after every successful run. Team members access the docs through the dbt Cloud web interface with no manual steps.

Automating Docs Generation

Add dbt docs generate at the end of your scheduled pipeline run:

# Example pipeline steps
dbt deps
dbt seed
dbt run
dbt test
dbt docs generate       ← runs after successful test step
# then upload to S3 or deploy to hosting

What to Do Before Running dbt docs generate

Step 1: dbt run          ← creates warehouse tables/views
Step 2: dbt test         ← optional, adds test results to docs
Step 3: dbt docs generate ← reads warehouse metadata + your YAML
Step 4: dbt docs serve   ← open in browser

If you run dbt docs generate before dbt run, the catalog will be empty because no warehouse objects exist yet.