diff --git a/website/docs/docs/guides/migration-guide/upgrading-to-0-18-0.md b/website/docs/docs/guides/migration-guide/upgrading-to-0-18-0.md
index 1646d962902..fb4acd420fd 100644
--- a/website/docs/docs/guides/migration-guide/upgrading-to-0-18-0.md
+++ b/website/docs/docs/guides/migration-guide/upgrading-to-0-18-0.md
@@ -45,3 +45,4 @@ Please be aware of the following changes in v0.18.0. While breaking, we do not e
- [model selection syntax](model-selection-syntax)
- [list (ls)](commands/list)
- [Redshift profile](redshift-profile#specifying-an-iam-profile)
+- [`asset-paths` config](asset-paths) (also updated [dbt_project.yml](dbt_project.yml.md) and the [description](description) docs to match)
diff --git a/website/docs/reference/dbt_project.yml.md b/website/docs/reference/dbt_project.yml.md
index 3a20e4fe9e9..256115a1238 100644
--- a/website/docs/reference/dbt_project.yml.md
+++ b/website/docs/reference/dbt_project.yml.md
@@ -23,6 +23,7 @@ dbt uses YAML in a few different places. If you're new to YAML, it would be wort
[macro-paths](project-configs/macro-paths): [directorypath]
[snapshot-paths](project-configs/snapshot-paths): [directorypath]
[docs-paths](project-configs/docs-paths): [directorypath]
+[asset-paths](project-configs/asset-paths): [directorypath]
[target-path](project-configs/target-path): directorypath
[log-path](project-configs/log-path): directorypath
diff --git a/website/docs/reference/project-configs/asset-paths.md b/website/docs/reference/project-configs/asset-paths.md
new file mode 100644
index 00000000000..3621cc133d6
--- /dev/null
+++ b/website/docs/reference/project-configs/asset-paths.md
@@ -0,0 +1,39 @@
+---
+datatype: [directorypath]
+default_value: []
+---
+
+
+
+```yml
+asset-paths: [directorypath]
+```
+
+
+
+## Definition
+Optionally specify a custom list of directories to copy to the `target` directory as part of the `docs generate` command. This is useful for rendering images in your repository in your project documentation.
+
+
+
+* `v0.18.0`: This configuration was introduced — see the [migration guide for 0.18.0](upgrading-to-0-18-0) for more details.
+
+
+
+## Default
+By default, dbt will not compile any additional files as part of `docs generate`, i.e. `analysis-paths: []`
+
+## Examples
+### Compile files in the `assets` subdirectory as part of `docs generate`
+
+
+
+```yml
+asset-paths: ["assets"]
+```
+
+
+
+Any files included in this directory will be copied to the `target/` directory as part of `dbt docs generate`, making them accessible as images in your project documentation.
+
+Check out the full writeup on including images in your descriptions [here](/reference/resource-properties/description/#include-an-image-from-your-repo-in-your-descriptions).
diff --git a/website/docs/reference/resource-properties/description.md b/website/docs/reference/resource-properties/description.md
index ef15583e2d1..f39be94ff13 100644
--- a/website/docs/reference/resource-properties/description.md
+++ b/website/docs/reference/resource-properties/description.md
@@ -292,7 +292,7 @@ You can use relative links to link to another model. It's a little hacky — but
version: 2
models:
- - name: dim_customers
+ - name: customers
description: "Filtering done based on \[stg_stripe__payments](#!/model/model.jaffle_shop.stg_stripe__payments)"
columns:
@@ -304,11 +304,20 @@ models:
-### Include an image in your descriptions
+### Include an image from your repo in your descriptions
+To include an image from your repository in your descriptions:
+1. Add the file in a subdirectory, e.g. `assets/dbt-logo.png`
+2. Set the [`asset-paths` config](project-configs/asset-paths) in your `dbt_project.yml` file so that this directory gets copied to the `target/` directory as part of `dbt docs generate`
+
+
+
+```yml
+asset-paths: ["assets"]
+```
-At present, it's not possible to include an image in your project and render it as part of your project documentation using the image path. This is because images are not included in the `target` directory when you execute `dbt compile`. We hope to address this in the future ([related issue](https://github.com/fishtown-analytics/dbt/issues/2072)).
+
-Instead, consider hosting the image online and using the image URL to render the image.
+2. Use a Markdown link to the image in your `description:`
@@ -316,8 +325,39 @@ Instead, consider hosting the image online and using the image URL to render the
version: 2
models:
- - name: dim_customers
- description: "!\[dbt Logo](https://github.com/fishtown-analytics/dbt/raw/master/etc/dbt-horizontal.png)"
+ - name: customers
+ description: "!\[dbt Logo](assets/dbt-logo.png)"
+
+ columns:
+ - name: customer_id
+ description: Primary key
+
+```
+
+
+
+_[CLI users only]_
+
+3. Run `dbt docs generate` — the `assets` directory will be copied to the `target` directory
+
+4. Run `dbt docs serve` — the image will be rendered as part of your project documentation:
+
+
+
+If mixing images and text together, also consider using a docs block.
+
+### Include an image from the web in your descriptions
+
+Use the image URL to render the image.
+
+
+
+```yml
+version: 2
+
+models:
+ - name: customers
+ description: "!\[dbt Logo](https://raw.githubusercontent.com/fishtown-analytics/dbt/dev/marian-anderson/etc/dbt-logo-full.svg)"
columns:
- name: customer_id
@@ -327,4 +367,4 @@ models:
-If mixing images and text together, consider using a docs block instead.
+If mixing images and text together, also consider using a docs block.
diff --git a/website/sidebars.js b/website/sidebars.js
index 345827eba20..6533ee6e7b4 100755
--- a/website/sidebars.js
+++ b/website/sidebars.js
@@ -204,6 +204,7 @@ module.exports = {
label: "Project configurations",
items: [
"reference/project-configs/analysis-paths",
+ "reference/project-configs/asset-paths",
"reference/project-configs/clean-targets",
"reference/project-configs/config-version",
"reference/project-configs/data-paths",
diff --git a/website/static/img/reference/image-in-docs.png b/website/static/img/reference/image-in-docs.png
new file mode 100644
index 00000000000..b3e87ef558e
Binary files /dev/null and b/website/static/img/reference/image-in-docs.png differ