# About documentation

Good documentation for your dbt models will help downstream consumers discover and understand the datasets you curate for them. dbt provides a way to generate documentation for your dbt project and render it as a website.

Tip

Use [dbt Wizard](../platform/wizard-overview.md) to generate documentation in the dbt platform or locally in the CLI.

## Related documentation

* [Declaring properties](../../reference/configs-and-properties.md)
* [`dbt docs` command](../../reference/commands/cmd-docs.md)
* [`doc` Jinja function](../../reference/dbt-jinja-functions/doc.md)
* If you're new to dbt, we recommend that you check out our [quickstart guide](../../guides.md) to build your first dbt project, complete with documentation.

## Assumed knowledge

* [Data tests](./data-tests.md)

## Overview

dbt provides a scalable way to [generate](#generating-documentation) documentation for your dbt project using descriptions and commands. The documentation for your project includes:

* **Information about your project**: including model code, a DAG of your project, any tests you've added to a column, and more.
* **Information about your data warehouse**: including column data types, and table sizes. This information is generated by running queries against the information schema.
* Importantly, dbt also provides a way to add **descriptions** to models, columns, sources, and more, to further enhance your documentation.

The following sections describe how to [add descriptions](#adding-descriptions-to-your-project) to your project, [generate documentation](#generating-documentation), how to use [docs blocks](#using-docs-blocks), and set a [custom overview](#setting-a-custom-overview) for your documentation.

## Adding descriptions to your project

Before generating documentation, add [descriptions](../../reference/resource-properties/description.md) to your project resources. Add the `description:` key to the same YAML files where you declare [data tests](./data-tests.md). For example:

models/\<filename>.yml

```yaml

models:
  - name: events
    description: This table contains clickstream events from the marketing website

    columns:
      - name: event_id
        description: This is a unique identifier for the event
        data_tests:
          - unique
          - not_null

      - name: user-id
        quote: true
        description: The user who performed the event
        data_tests:
          - not_null
```

### FAQs

Are there any example dbt documentation sites?

Yes!

* **Quickstart Tutorial:** You can build your own example dbt project in the [quickstart guide](../get-started-dbt.md)
* **Jaffle Shop:** A demonstration project (closely related to the tutorial) for a fictional e-commerce store. Refer to [Clone the Jaffle Shop sample project](../../guides/clone-jaffle-shop.md) for clone instructions, or view the [main source code](https://github.com/dbt-labs/jaffle-shop) and [source code using DuckDB](https://github.com/dbt-labs/jaffle_shop_duckdb) on GitHub.
* **GitLab:** Gitlab's internal dbt project is open source and is a great example of how to use dbt at scale ([source code](https://gitlab.com/gitlab-com/content-sites/handbook/blob/main/content/handbook/enterprise-data/platform/dbt-guide.md))
* **dummy-dbt:** A containerized dbt project that populates the Sakila database in Postgres and populates dbt seeds, models, snapshots, and tests. The project can be used for testing and experimentation purposes ([source code](https://github.com/gmyrianthous/dbt-dummy))
* **Google Analytics 4:** A demonstration project that transforms the Google Analytics 4 BigQuery exports to various models ([source code](https://github.com/stacktonic-com/stacktonic-dbt-example-project), [docs](https://stacktonic.com/article/google-analytics-big-query-and-dbt-a-dbt-example-project))
* **Make Open Data:** A production-grade ELT with tests, documentation, and CI/CD (GHA) about French open data (housing, demography, geography, etc). It can be used to learn with voluminous and ambiguous data. Contributions are welcome ([source code](https://github.com/make-open-data/make-open-data), [docs](https://make-open-data.fr/))

If you have an example project to add to this list, suggest an edit by clicking **Edit this page** below.

Do I need to add a YAML entry for column for it to appear in the docs site?

Fortunately, no!

dbt will introspect your warehouse to generate a list of columns in each relation, and match it with the list of columns in your `.yml` files. As such, any undocumented columns will still appear in your documentation!

How do I write long-form explanations in my descriptions?

If you need more than a sentence to explain a model, you can:

1. Split your description over multiple lines using `>`. Interior line breaks are removed and Markdown can be used. This method is recommended for simple, single-paragraph descriptions:

```yml
models:
  - name: customers
    description: >
      Lorem ipsum **dolor** sit amet, consectetur adipisicing elit, sed do eiusmod
      tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam,
      quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo
      consequat.
```

2. Split your description over multiple lines using `|`. Interior line breaks are maintained and Markdown can be used. This method is recommended for more complex descriptions:

```yml
models:
  - name: customers
    description: |
      ### Lorem ipsum

      * dolor sit amet, consectetur adipisicing elit, sed do eiusmod
      * tempor incididunt ut labore et dolore magna aliqua.
```

3. Use a [docs block](./documentation.md#using-docs-blocks) to write the description in a separate Markdown file.

How do I access documentation in dbt Catalog?

If you're using dbt to deploy your project and have a [Starter, Enterprise, or Enterprise+ plan](https://www.getdbt.com/pricing/), you can use Catalog to view your project's [resources](./projects.md) (such as models, tests, and metrics) and their lineage to gain a better understanding of its latest production state.

Access Catalog in dbt by clicking the **Catalog** link in the navigation. You can have up to 5 read-only users access the documentation for your project.

dbt developer plan and dbt Core users can use [dbt Docs](../explore/build-and-view-your-docs.md#dbt-docs), which generates basic documentation but it doesn't offer the same speed, metadata, or visibility as Catalog.

Can I document things other than models, like sources, seeds, and snapshots?

Yes! You can document almost everything in your project using the `description:` key. Check out the reference docs on [descriptions](../../reference/resource-properties/description.md) for more info!

## Generating documentation

(Applies to dbt v2.0 and later)

Using the dbt Fusion engine, dbt Docs v2 replaces the v1 static site with a modern, performant catalog. `dbt docs generate` compiles your project, produces the v2 Parquet artifacts, and writes a static site that the browser queries directly with DuckDB-WASM (WebAssembly), so you don't need a server to view it. To generate and serve documentation:

1. Run `dbt docs generate` to compile your project, write the index, and export the documentation site in a single command.
2. Run `dbt docs serve` to preview the site locally.

Refer to [dbt docs commands](../../reference/commands/cmd-docs.md) for full usage details.

dbt provides three complementary ways to [view documentation](./view-documentation.md) after descriptions are generated:

* [**dbt Docs (Legacy)**](./view-documentation.md#dbt-docs): A static documentation site with model lineage, metadata, and documentation that can be hosted on your web server (like S3 or Netlify). Available for dbt Core v1.x or dbt Developer plans.
* [**dbt Docs v2**](./view-documentation.md#dbt-docs-v2) [Beta](https://docs.getdbt.com/docs/dbt-versions/product-lifecycles "Go to https://docs.getdbt.com/docs/dbt-versions/product-lifecycles"): A modern, performant open-source catalog with a redesigned UI, Semantic Layer metadata, and column-level lineage, served as a static site you can host anywhere. Available with the dbt Fusion engine and dbt Core 2.0.
* [**Catalog**](../explore/explore-projects.md): Builds upon dbt Docs to provide a dynamic, real-time interface with enhanced metadata, customizable views, deeper project insights, and collaboration tools. Available on dbt [Starter, Enterprise, or Enterprise+ plans](https://www.getdbt.com/pricing).

Refer to [View documentation](./view-documentation.md) to get the most out of your dbt project's documentation.

## Using docs blocks

Docs blocks provide a robust method for documenting models and other resources using Jinja and markdown. Docs block files can contain arbitrary markdown, but they must be uniquely named.

### Syntax

To declare a docs block, use the Jinja `docs` tag. The name of a docs block can't start with a digit and may contain:

* Uppercase and lowercase letters (A-Z, a-z)
* Digits (0-9)
* Underscores (\_)

events.md

```markdown
{% docs table_events %}

This table contains clickstream events from the marketing website.

The events in this table are recorded by Snowplow and piped into the warehouse on an hourly basis. The following pages of the marketing site are tracked:
 - /
 - /about
 - /team
 - /contact-us

{% enddocs %}
```

In this example, a docs block named `table_events` is defined with some descriptive markdown contents. There is nothing significant about the name `table_events` — docs blocks can be named however you like, as long as the name only contains alphanumeric and underscore characters and doesn't start with a numeric character.

### Placement

(Applies to dbt v1.12 and later)

Place docs blocks in `.md` files. You can also use Jinja-style extensions (`.md.j2`, `.md.jinja`, `.md.jinja2`), however these require setting [`allow_jinja_file_extensions: true`](../../reference/global-configs/behavior-flags/allow_jinja_file_extensions.md) in your `dbt_project.yml`. This enables Jinja-aware syntax highlighting in IDEs that associate these suffixes with Jinja templating.

By default, dbt searches in all resource paths for docs blocks (for example, the combined list of [model-paths](../../reference/project-configs/model-paths.md), [seed-paths](../../reference/project-configs/seed-paths.md), [analysis-paths](../../reference/project-configs/analysis-paths.md), [test-paths](../../reference/project-configs/test-paths.md), [macro-paths](../../reference/project-configs/macro-paths.md), and [snapshot-paths](../../reference/project-configs/snapshot-paths.md)). You can adjust this behavior using the [docs-paths](../../reference/project-configs/docs-paths.md) config.

### Usage

To use a docs block, reference it from your `schema.yml` file with the [doc()](../../reference/dbt-jinja-functions/doc.md) function in place of a markdown string. Using the examples above, the `table_events` docs can be included in the `schema.yml` file as shown here:

schema.yml

```yaml

models:
  - name: events
    description: '{{ doc("table_events") }}'

    columns:
      - name: event_id
        description: This is a unique identifier for the event
        data_tests:
            - unique
            - not_null
```

In the resulting documentation, `'{{ doc("table_events") }}'` will be expanded to the markdown defined in the `table_events` docs block.

## Setting a custom overview

Availability

This feature is available only in [dbt Docs](./documentation.md), the generated documentation site for your dbt project.

The "overview" shown in the dbt Docs website can be overridden by supplying your own docs block called `__overview__`.

* By default, dbt supplies an overview with helpful information about the docs site itself.
* Depending on your needs, it may be a good idea to override this docs block with specific information about your company style guide, links to reports, or information about who to contact for help.
* To override the default overview, create a docs block that looks like this:

models/overview\.md

```markdown
{% docs __overview__ %}
# Monthly Recurring Revenue (MRR) playbook.
This dbt project is a worked example to demonstrate how to model subscription
revenue. **Check out the full write-up [here](https://blog.getdbt.com/modeling-subscription-revenue/),
as well as the repo for this project [here](https://github.com/dbt-labs/mrr-playbook/).**
...

{% enddocs %}
```

### Custom project-level overviews

You can set different overviews for each dbt project/package included in your documentation site by creating a docs block named `__[project_name]__`.

For example, in order to define custom overview pages that appear when a viewer navigates inside the `dbt_utils` or `snowplow` package:

models/overview\.md

```markdown
{% docs __dbt_utils__ %}
# Utility macros
Our dbt project heavily uses this suite of utility macros, especially:
- `surrogate_key`
- `test_equality`
- `pivot`
{% enddocs %}

{% docs __snowplow__ %}
# Snowplow sessionization
Our organization uses this package of transformations to roll Snowplow events
up to page views and sessions.
{% enddocs %}
```

## Was this page helpful?

YesNo

[Privacy policy](https://www.getdbt.com/cloud/privacy-policy)[Create a GitHub issue](https://github.com/dbt-labs/docs.getdbt.com/issues)

This site is protected by reCAPTCHA and the Google [Privacy Policy](https://policies.google.com/privacy) and [Terms of Service](https://policies.google.com/terms) apply.