Docs updates by matthewshaver · Pull Request #9830 · dbt-labs/docs.getdbt.com

matthewshaver · 2026-08-17T20:57:58Z

What are you changing in this pull request and why?

Updates the dbt docs command reference (Fusion v2.0 section) to reflect recent dbt-labs/fs changes and to lead with dbt Docs v2 as the recommended solution, followed by --write-catalog.

Key changes:

Reordered so dbt Docs v2 leads (framed as the solution); --write-catalog follows.
Rewrote dbt Docs v2 as a static site (dbt docs generate exports static files queried in-browser via DuckDB-WASM) — no more stateful server (fs#12854).
Removed the REST API section — the /api/v1/* API was deleted (fs#12854).
dbt docs generate now compiles the index itself — dropped the "run --write-index first" steps; documented --no--compile and --output-dir (fs#13149).
Lifecycle badge alpha → beta (fs#13163).

Checklist

The changes in this PR meet the docs style guide/fundamentals required for all content.
Applied the proper versioning rules if the content is for specific dbt version(s): (version a whole page or version a block of content
The content in this PR requires a dbt release note, so I added one to the release notes page.).

🚀 Deployment available! Here are the direct links to the updated files:

vercel · 2026-08-17T20:58:05Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs-getdbt-com	Ready	Preview	Aug 19, 2026 7:48pm

runleonarun

@matthewshaver Just a few questions!

runleonarun · 2026-08-18T21:42:43Z

- `dbt run`
- `dbt parse`
- `dbt compile`
+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.


Can we link to something that explains DuckDB-WASM? Or at least spell out WASM for those of us who don't know it stands for WebAssembly.

runleonarun · 2026-08-18T22:13:34Z

+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 <Constant name="core_v1" />. 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.


matching the layout of

Do you mean Docs v1?

v1 in this case is referring to Core v1 but they're sort of synonymous at this stage

runleonarun · 2026-08-18T22:14:53Z

+```

-When running <Constant name="fusion" /> locally, add the `--write-catalog` flag to your command to generate the catalog:
+To skip compilation and export whatever index is already on disk, use `--no-compile`. This errors if no index exists:


Suggested change

To skip compilation and export whatever index is already on disk, use `--no-compile`. This errors if no index exists:

To skip compilation and export whatever index is already on disk, use `--no-compile`, which fails with an error if no index exists:

runleonarun · 2026-08-18T22:26:22Z

-### REST API
+### Platform behavior
+
+In <Constant name="dbt_platform" /> jobs running on <Constant name="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 <Constant name="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`.


the platform automatically uses --write-catalog instead.

Instead of generating the docs site? I'm confused because I thought --write-catalog "focuses solely on metadata hydration and does not build the documentation site" But I also thought docs generate builds the docs v2 site in dbt platform?

@eliasdefaria good question here. ARe the changes you've made explicitly for the local experience? Does anything change platform side?

Platform side should just work if you run docs generate or turn it on in your jobs. Otherwise it does not produce the static site

eliasdefaria · 2026-08-19T16:50:33Z

 <VersionBlock firstVersion="2.0">

-Using the <Constant name="fusion_engine" />, dbt Docs v2 replaces the v1 static site with a modern, performant catalog served through a local REST API. To generate and serve documentation:
+Using the <Constant name="fusion_engine" />, dbt Docs v2 replaces the v1 static site with a modern, performant catalog. `dbt docs generate` writes a static site — a single-page app plus a compact binary index — that the browser queries directly with DuckDB-WASM, so you don't need a server to view it. To generate and serve documentation:


It's not a compact binary index I don't know what that is.

It writes a static site + plus compiles the project and produces the new v2 parquet artifacts.

eliasdefaria · 2026-08-19T16:52:01Z

-```bash
-DBT_TARGET_PATH=/abs/path/to/project/target docker compose up --build
-```
+To include column-level lineage and richer column metadata, first build the index with [`--static-analysis strict`](https://docs.getdbt.com/docs/build/about-static-analysis?version=1.13), then export it:


We should be clear about what to run here. Specifically dbt compile --write-index --static-analysis strict.

You can also note that we are making CLL work in baseline mode, so soon CLL will work when you run dbt docs generate alone

I see you have build below, so you can also mention that as an option

eliasdefaria · 2026-08-19T16:53:23Z


+### dbt Docs v2
+
+v2 introduces [dbt Docs v2](/docs/build/view-documentation#dbt-docs-v2), a faster, statically hostable documentation experience that replaces the v1 static site. `dbt docs generate` now compiles your project, writes a compact binary index, and exports a static site in a single command &mdash; you no longer run `--write-index` separately. `dbt docs serve` previews that site locally, and because the browser queries the index directly with DuckDB-WASM, you can also host the generated files on any static file host.


Again no binary index.

Also can we make this more future proofed? We don't need to imply that previously you had to do --write-index. We can just say --write-index is only necessary if you want to produce the artifacts from a dbt compile or dbt build command

eliasdefaria · 2026-08-19T16:53:53Z

- `dbt run`
- `dbt parse`
- `dbt compile`
+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.


Again no company binary index. It just produces the parquet artifacts instead of manifest json

eliasdefaria · 2026-08-19T16:55:12Z

-### REST API
+### Platform behavior
+
+In <Constant name="dbt_platform" /> jobs running on <Constant name="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 <Constant name="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`.


Platform side should just work if you run docs generate or turn it on in your jobs. Otherwise it does not produce the static site

runleonarun

Looks good!

Docs updates (DRAFT)

470c7d8

matthewshaver requested a review from a team as a code owner August 17, 2026 20:57

github-actions Bot added content Improvements or additions to content Docs team Authored by the Docs team @dbt Labs labels Aug 17, 2026

vercel Bot deployed to Preview August 17, 2026 21:01 View deployment

Updates

abac3d7

matthewshaver changed the title ~~Docs updates (DRAFT)~~ Docs updates Aug 18, 2026

vercel Bot deployed to Preview August 18, 2026 21:06 View deployment

runleonarun reviewed Aug 18, 2026

View reviewed changes

Updates

ae889be

vercel Bot deployed to Preview August 19, 2026 02:58 View deployment

Style updates

67e4864

vercel Bot deployed to Preview August 19, 2026 03:06 View deployment

Adding clarifying statement

42548bd

vercel Bot deployed to Preview August 19, 2026 03:11 View deployment

Adding to upgrade guide

ae5ae77

vercel Bot deployed to Preview August 19, 2026 03:17 View deployment

eliasdefaria reviewed Aug 19, 2026

View reviewed changes

matthewshaver added 2 commits August 19, 2026 14:32

Updates based on feedback

7c563c3

One more

51ede7d

matthewshaver requested review from eliasdefaria and runleonarun August 19, 2026 18:34

vercel Bot deployed to Preview August 19, 2026 18:40 View deployment

Removing --write-index mention

12ef901

eliasdefaria approved these changes Aug 19, 2026

View reviewed changes

vercel Bot deployed to Preview August 19, 2026 19:24 View deployment

Merge branch 'current' into docs-v2

7fd2cfc

vercel Bot deployed to Preview August 19, 2026 19:32 View deployment

Removing v1 only mention

db32fcd

runleonarun approved these changes Aug 19, 2026

View reviewed changes

vercel Bot deployed to Preview August 19, 2026 19:48 View deployment

matthewshaver merged commit 22d185c into current Aug 19, 2026
5 checks passed

matthewshaver deleted the docs-v2 branch August 19, 2026 19:50

	To skip compilation and export whatever index is already on disk, use `--no-compile`. This errors if no index exists:
	To skip compilation and export whatever index is already on disk, use `--no-compile`, which fails with an error if no index exists:


		### dbt Docs v2

		v2 introduces [dbt Docs v2](/docs/build/view-documentation#dbt-docs-v2), a faster, statically hostable documentation experience that replaces the v1 static site. `dbt docs generate` now compiles your project, writes a compact binary index, and exports a static site in a single command — you no longer run `--write-index` separately. `dbt docs serve` previews that site locally, and because the browser queries the index directly with DuckDB-WASM, you can also host the generated files on any static file host.

Uh oh!

Conversation

matthewshaver commented Aug 17, 2026 • edited by github-actions Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

What are you changing in this pull request and why?

Checklist

Uh oh!

vercel Bot commented Aug 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

runleonarun left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

runleonarun left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

matthewshaver commented Aug 17, 2026 •

edited by github-actions Bot

Loading

vercel Bot commented Aug 17, 2026 •

edited

Loading