How to Generate Docs in dbt: Step-by-Step Guide

To generate docs in dbt, run dbt docs generate to create the documentation site files. Then use dbt docs serve to start a local web server and view the docs in your browser.

Syntax

The main commands to generate and view docs in dbt are:

• dbt docs generate: Builds the documentation site files from your project and database metadata.
• dbt docs serve: Starts a local web server to browse the generated docs.

You run these commands in your terminal inside your dbt project folder.

bash

dbt docs generate
dbt docs serve

Example

This example shows how to generate and view docs for a dbt project:

1. Open your terminal and navigate to your dbt project folder.
2. Run dbt docs generate to create the docs files.
3. Run dbt docs serve to start a local server.
4. Open the URL shown in the terminal (usually http://localhost:8080) in your browser to see the docs.

bash

cd my_dbt_project

dbt docs generate

dbt docs serve

Output

Serving docs at http://localhost:8080
Press Ctrl+C to stop.

Common Pitfalls

Common mistakes when generating docs in dbt include:

• Running dbt docs serve before dbt docs generate, which means no docs are available to serve.
• Not running the commands inside the correct dbt project directory.
• Not having your models properly documented with description fields in your schema files, resulting in sparse docs.
• Firewall or network issues blocking access to localhost:8080 when serving docs.

bash

## Wrong order (no docs generated yet)
dbt docs serve

## Correct order
dbt docs generate
dbt docs serve

Quick Reference

Command	Purpose
dbt docs generate	Builds the documentation site files
dbt docs serve	Starts a local server to view docs
description in schema.yml	Add descriptions to models and columns for richer docs

Key Takeaways

Always run dbt docs generate before dbt docs serve to create docs files.

Use dbt docs serve to open your docs in a web browser locally.

Add description fields in your schema.yml files to improve documentation quality.

Run commands inside your dbt project folder to avoid errors.

Check your network settings if you cannot access the docs at localhost.