What dbt docs generate actually produces

When you run dbt docs generate, dbt produces a static website. Understanding what that command actually creates helps you make informed decisions about hosting, automation, and when the default frontend stops scaling.

The three output files

The command produces three artifacts in your target/ directory:

1. index.html — The frontend shell. This is a single-page application (SPA) that renders everything client-side. dbt copies this file from its internal templates; you do not write or modify it.

2. manifest.json — Your compiled project metadata. Models, sources, tests, macros, exposures, and their relationships. The compiled_code field appears here, showing the fully rendered SQL for each model after Jinja processing. This is the same manifest that powers dbt ls, dbt run --select, and every other project introspection command.

3. catalog.json — Database metadata. Column types, row counts, table statistics. This is the only artifact that requires a live database connection, because dbt queries your warehouse’s INFORMATION_SCHEMA (or equivalent) to build it.

Together, the HTML shell loads both JSON files and renders the documentation site entirely in the browser. There is no server-side processing after the initial generation step.

Flags that matter

--select

Limits catalog generation to specific nodes:

dbt docs generate --select marts.*

For large projects, this dramatically speeds up generation. The manifest is always complete (it reflects your entire project), but the catalog only includes metadata for selected models. Unselected models still appear in the docs site but without column-level details.

--no-compile

Skips recompilation if your manifest is already current:

dbt docs generate --no-compile

Useful in CI pipelines where you have already run dbt compile or dbt run earlier in the same job. The manifest from that step is reused, saving compilation time.

--static

This is the most consequential flag for deployment:

dbt docs generate --static

Without --static, you get three separate files that require a web server capable of serving the JSON alongside the HTML. The SPA makes requests to load manifest.json and catalog.json at runtime.

With --static, dbt produces a single static_index.html file with both JSON payloads embedded inline. This file is completely self-contained. You can open it directly in a browser, host it on any static file server, or email it as an attachment (though at scale, it can be very large).

For deployment to GitHub Pages, Netlify, or cloud storage, the --static flag simplifies hosting because you only need to serve one file. The trade-off is file size: a project with a large manifest and catalog produces a static_index.html that can be tens of megabytes.

dbt docs serve is a preview tool

dbt docs serve --port 8080

This starts a local web server to preview the generated site. dbt’s own documentation explicitly states that dbt docs serve is not intended for production use. It is a development convenience, not a deployment strategy.

The server has no authentication, no caching, no TLS, and no concurrency handling. It serves the files from your target/ directory directly. For anything beyond “I want to check how my docs look right now,” you need a proper hosting solution.

How generation fits into a pipeline

A typical documentation pipeline runs these steps:

1. dbt run (or dbt build) — materializes models, producing manifest.json
2. dbt docs generate — queries the database for catalog metadata, produces catalog.json and index.html
3. Deploy the target/ contents (or static_index.html) to your hosting platform

Step 2 needs database access because it queries warehouse metadata. If you run docs generation in CI, your CI environment needs credentials with at least read access to the schemas your models materialize into. The --select flag can limit which schemas are queried if your CI service account has restricted permissions.

For automated deployment, this pipeline typically runs on merge to main, ensuring the hosted docs always reflect the latest production state of your project.