About dbt docs commands
With the dbt Fusion engine and dbt Core 2.0, dbt Docs v2 is the recommended way to generate and view your project's documentation. Use dbt docs generate to build the documentation site and dbt docs serve to preview it locally.
If you only need to hydrate catalog metadata (catalog.json) for Catalog in dbt platform, without building the documentation site, use the --write-catalog flag instead.
dbt Docs v2 Beta
Instead of loading a static manifest.json in the browser, v2 builds a compact binary index of your project. dbt docs generate exports a documentation site made of plain static files (a single-page app plus the index artifacts) that any file host can serve. The browser reads those artifacts directly using DuckDB-WASM, so you don't need to run a stateful server to view your docs. This keeps the experience fast even for large projects.
Generate the site
dbt docs generate compiles your project, writes the index, and exports the documentation site in a single command. You no longer need to run a separate --write-index command first:
dbt docs generate
By default, dbt writes the site into your target/ directory (target/index.html, target/assets/, and the index under target/index/), matching the layout of dbt Core v1.x. You can serve index.html from target/ the same way you did in v1, so existing CI such as dbt docs generate && mv target public continues to work.
Use --output-dir to write a self-contained copy of the site to a different directory:
dbt docs generate --output-dir site
To skip compilation and export whatever index is already on disk, use --no-compile. This errors if no index exists:
dbt docs generate --no-compile
Column lineage and richer metadata
Column-level lineage and richer column metadata require an index built with --static-analysis strict. Because dbt docs generate runs a standard compile by default, build the index with strict static analysis first when you want column lineage, then export it:
dbt build --write-index --static-analysis strict
dbt docs generate --no-compile
If the site was generated without column lineage, dbt Docs v2 hides those features instead of showing empty data.
Serve dbt Docs v2
To preview the site locally, run:
dbt docs serve
dbt docs serve generates the site if it's missing or older than the index, then serves the static files. The server starts on port 8580 by default and opens in your browser. Use --port to change the port:
dbt docs serve --port 8081
Use the --target-path flag to change the path where dbt reads artifacts from:
dbt docs serve --target-path ~/Developer/internal-analytics/target
Because the generated site is a set of static files, you can also host it on any static file host — such as cloud object storage or a static site host — instead of serving it locally.
Project overview page
dbt Docs v2 renders your project's __overview__ doc block as the landing page, the same as dbt Docs v1. dbt discovers overview content by scanning your docs-paths for {% docs %} blocks, so a block in models/overview.md is found by default. A file at docs/overview.md is only picked up when your project sets docs-paths: ["docs"]. If your project defines no overview, dbt renders its default overview content.
--write-catalog flag
The --write-catalog flag generates the catalog.json artifact, which contains metadata about the tables and views produced by the models in your project. It focuses solely on metadata hydration and does not build the documentation site — use dbt Docs v2 for that.
For Fusion jobs running in dbt platform, dbt automatically runs write-catalog with build and run and hydrates your Catalog, so you don't need to include it manually. You can use this flag with the following commands:
dbt builddbt rundbt parsedbt compile
Example:
dbt build --write-catalog
Platform behavior
In dbt platform jobs running on Fusion, you don't need to change anything. When dbt docs generate is called (either as a job step or separate command), the platform automatically uses --write-catalog instead. Additionally, for Fusion jobs running in the platform, dbt runs write-catalog automatically with build or run, so you don't need to run a separate command to hydrate your metadata. In the platform, you can optionally choose to include it when running dbt parse or dbt compile.
Local usage
When running Fusion locally, add the --write-catalog flag to your command to generate the catalog:
dbt build --write-catalog
What's different from docs generate
The --write-catalog flag focuses solely on metadata hydration, generating the catalog.json file that powers Catalog and metadata APIs. It does not generate the static documentation website files (index.html).
Was this page helpful?
This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.
