diff --git a/website/docs/reference/project-configs/analysis-paths.md b/website/docs/reference/project-configs/analysis-paths.md
index 5c3d223a5cb..20e2e65c2ad 100644
--- a/website/docs/reference/project-configs/analysis-paths.md
+++ b/website/docs/reference/project-configs/analysis-paths.md
@@ -13,12 +13,31 @@ analysis-paths: [directorypath]
## Definition
-Specify a custom list of directories where [analyses](/docs/build/analyses) are located.
+Specify a custom list of directories where [analyses](/docs/build/analyses) are located.
## Default
Without specifying this config, dbt will not compile any `.sql` files as analyses.
-However, the [`dbt init` command](/reference/commands/init) populates this value as `analyses` ([source](https://github.com/dbt-labs/dbt-starter-project/blob/HEAD/dbt_project.yml#L15))
+However, the [`dbt init` command](/reference/commands/init) populates this value as `analyses` ([source](https://github.com/dbt-labs/dbt-starter-project/blob/HEAD/dbt_project.yml#L15)).
+
+import RelativePath from '/snippets/_relative-path.md';
+
+
+
+- ✅ **Do**
+ - Use relative path:
+ ```yml
+ analysis-paths: ["analyses"]
+ ```
+
+- ❌ **Don't**
+ - Avoid absolute paths:
+ ```yml
+ analysis-paths: ["/Users/username/project/analyses"]
+ ```
## Examples
### Use a subdirectory named `analyses`
diff --git a/website/docs/reference/project-configs/asset-paths.md b/website/docs/reference/project-configs/asset-paths.md
index 1fb3cf9f260..effae8bad7f 100644
--- a/website/docs/reference/project-configs/asset-paths.md
+++ b/website/docs/reference/project-configs/asset-paths.md
@@ -15,8 +15,29 @@ 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.
+
## Default
-By default, dbt will not copy any additional files as part of docs generate, i.e. `asset-paths: []`
+
+By default, dbt will not copy any additional files as part of docs generate. For example, `asset-paths: []`.
+
+import RelativePath from '/snippets/_relative-path.md';
+
+
+
+- ✅ **Do**
+ - Use relative path:
+ ```yml
+ asset-paths: ["assets"]
+ ```
+
+- ❌ **Don't**
+ - Avoid absolute paths:
+ ```yml
+ asset-paths: ["/Users/username/project/assets"]
+ ```
## Examples
### Compile files in the `assets` subdirectory as part of `docs generate`
diff --git a/website/docs/reference/project-configs/docs-paths.md b/website/docs/reference/project-configs/docs-paths.md
index 5481c19c9fd..6cd179201fc 100644
--- a/website/docs/reference/project-configs/docs-paths.md
+++ b/website/docs/reference/project-configs/docs-paths.md
@@ -30,6 +30,25 @@ By default, dbt will search in all resource paths for docs blocks (i.e. the comb
+import RelativePath from '/snippets/_relative-path.md';
+
+
+
+- ✅ **Do**
+ - Use relative path:
+ ```yml
+ docs-paths: ["docs"]
+ ```
+
+- ❌ **Don't**
+ - Avoid absolute paths:
+ ```yml
+ docs-paths: ["/Users/username/project/docs"]
+ ```
+
## Example
Use a subdirectory named `docs` for docs blocks:
diff --git a/website/docs/reference/project-configs/macro-paths.md b/website/docs/reference/project-configs/macro-paths.md
index 486ec08ffdf..d790899689e 100644
--- a/website/docs/reference/project-configs/macro-paths.md
+++ b/website/docs/reference/project-configs/macro-paths.md
@@ -16,7 +16,26 @@ macro-paths: [directorypath]
Optionally specify a custom list of directories where [macros](/docs/build/jinja-macros#macros) are located. Note that you cannot co-locate models and macros.
## Default
-By default, dbt will search for macros in a directory named `macros`, i.e. `macro-paths: ["macros"]`
+By default, dbt will search for macros in a directory named `macros`. For example, `macro-paths: ["macros"]`.
+
+import RelativePath from '/snippets/_relative-path.md';
+
+
+
+- ✅ **Do**
+ - Use relative path:
+ ```yml
+ macro-paths: ["macros"]
+ ```
+
+- ❌ **Don't:**
+ - Avoid absolute paths:
+ ```yml
+ macro-paths: ["/Users/username/project/macros"]
+ ```
## Examples
### Use a subdirectory named `custom_macros` instead of `macros`
diff --git a/website/docs/reference/project-configs/model-paths.md b/website/docs/reference/project-configs/model-paths.md
index a0652432787..f01dd29a8fd 100644
--- a/website/docs/reference/project-configs/model-paths.md
+++ b/website/docs/reference/project-configs/model-paths.md
@@ -15,7 +15,26 @@ model-paths: [directorypath]
Optionally specify a custom list of directories where [models](/docs/build/models) and [sources](/docs/build/sources) are located.
## Default
-By default, dbt will search for models and sources in the `models` directory, i.e. `model-paths: ["models"]`
+By default, dbt will search for models and sources in the `models` directory. For example, `model-paths: ["models"]`.
+
+import RelativePath from '/snippets/_relative-path.md';
+
+
+
+- ✅ **Do**
+ - Use relative path:
+ ```yml
+ model-paths: ["models"]
+ ```
+
+- ❌ **Don't:**
+ - Avoid absolute paths:
+ ```yml
+ model-paths: ["/Users/username/project/models"]
+ ```
## Examples
### Use a subdirectory named `transformations` instead of `models`
diff --git a/website/docs/reference/project-configs/seed-paths.md b/website/docs/reference/project-configs/seed-paths.md
index 614bda62cd2..d99c1b5a907 100644
--- a/website/docs/reference/project-configs/seed-paths.md
+++ b/website/docs/reference/project-configs/seed-paths.md
@@ -16,7 +16,26 @@ Optionally specify a custom list of directories where [seed](/docs/build/seeds)
## Default
-By default, dbt expects seeds to be located in the `seeds` directory, i.e. `seed-paths: ["seeds"]`
+By default, dbt expects seeds to be located in the `seeds` directory. For example, `seed-paths: ["seeds"]`.
+
+import RelativePath from '/snippets/_relative-path.md';
+
+
+
+- ✅ **Do**
+ - Use relative path:
+ ```yml
+ seed-paths: ["seed"]
+ ```
+
+- ❌ **Don't:**
+ - Avoid absolute paths:
+ ```yml
+ seed-paths: ["/Users/username/project/seed"]
+ ```
## Examples
### Use a subdirectory named `custom_seeds` instead of `seeds`
diff --git a/website/docs/reference/project-configs/snapshot-paths.md b/website/docs/reference/project-configs/snapshot-paths.md
index 8319833f1e6..a4dd5af9434 100644
--- a/website/docs/reference/project-configs/snapshot-paths.md
+++ b/website/docs/reference/project-configs/snapshot-paths.md
@@ -24,7 +24,27 @@ Note that you cannot co-locate models and snapshots. However, in [Versionless](/
## Default
-By default, dbt will search for snapshots in the `snapshots` directory, i.e. `snapshot-paths: ["snapshots"]`
+By default, dbt will search for snapshots in the `snapshots` directory. For example, `snapshot-paths: ["snapshots"]`.
+
+
+import RelativePath from '/snippets/_relative-path.md';
+
+
+
+- ✅ **Do**
+ - Use relative path:
+ ```yml
+ snapshot-paths: ["snapshots"]
+ ```
+
+- ❌ **Don't:**
+ - Avoid absolute paths:
+ ```yml
+ snapshot-paths: ["/Users/username/project/snapshots"]
+ ```
## Examples
### Use a subdirectory named `archives` instead of `snapshots`
diff --git a/website/docs/reference/project-configs/test-paths.md b/website/docs/reference/project-configs/test-paths.md
index 6749a07d23d..ab816eec973 100644
--- a/website/docs/reference/project-configs/test-paths.md
+++ b/website/docs/reference/project-configs/test-paths.md
@@ -21,6 +21,25 @@ Without specifying this config, dbt will search for tests in the `tests` directo
- Generic test definitions in the `tests/generic` subdirectory
- Singular tests (all other files)
+import RelativePath from '/snippets/_relative-path.md';
+
+
+
+- ✅ **Do**
+ - Use relative path:
+ ```yml
+ test-paths: ["test"]
+ ```
+
+- ❌ **Don't:**
+ - Avoid absolute paths:
+ ```yml
+ test-paths: ["/Users/username/project/test"]
+ ```
+
## Examples
### Use a subdirectory named `custom_tests` instead of `tests` for data tests
diff --git a/website/snippets/_relative-path.md b/website/snippets/_relative-path.md
new file mode 100644
index 00000000000..791f8e83f7e
--- /dev/null
+++ b/website/snippets/_relative-path.md
@@ -0,0 +1 @@
+Paths specified in {props.path}
must be relative to the location of your `dbt_project.yml` file. Avoid using absolute paths like {props.absolute}
, as it will lead to unexpected behavior and outcomes.