clarify macro properties aren't supported in dbt_project.yml

website/docs/docs/build/semantic-models.md

@@ -8,11 +8,25 @@ sidebar_label: Semantic models
 tags: [Metrics, Semantic Layer]
 ---
 
+import PropsCallout from '/snippets/_config-prop-callout.md';
+
 Semantic models serve as the foundation for defining data in MetricFlow, which powers the dbt Semantic Layer. You can think of semantic models as nodes in your semantic graph, connected via entities as edges. MetricFlow takes semantic models defined in YAML configuration files as inputs and creates a semantic graph that can be used to query metrics.
 
 Each semantic model corresponds to a dbt model in your DAG. Therefore you will have one YAML config for each semantic model in your dbt project. You can create multiple semantic models out of a single dbt model, as long as you give each semantic model a unique name. 
 
-You can configure semantic models in your dbt project directory in a `YAML` file. Depending on your project structure, you can nest semantic models under a `metrics:` folder or organize them under project sources. 
+<VersionBlock firstVersion="1.7">
+
+You can configure semantic models in your dbt project directory in a `YAML` file, _except_ the `dbt_project.yml` file. Depending on your project structure, you can nest semantic models under a `metrics:` folder or organize them under project sources. 
+
+</VersionBlock>
+
+<VersionBlock lastVersion="1.6">
+
+You can configure semantic models in your dbt project directory in a `YAML` file, _except_ the `dbt_project.yml` file. <PropsCallout title={frontMatter.title}/> 
+
+Depending on your project structure, you can nest semantic models under a `metrics:` folder or organize them under project sources.
+
+</VersionBlock>
 
 Semantic models have 6 components and this page explains the definitions with some examples:
 

website/docs/reference/analysis-properties.md

@@ -2,7 +2,9 @@
 title: Analysis properties
 ---
 
-We recommend you define analysis properties in your `analyses/` directory, which is illustrated in the [`analysis-paths`](/reference/project-configs/analysis-paths) configuration.
+import PropsCallout from '/snippets/_config-prop-callout.md';
+
+We recommend you define analysis properties in your `analyses/` directory, which is illustrated in the [`analysis-paths`](/reference/project-configs/analysis-paths) configuration. <PropsCallout title={frontMatter.title}/>  <br /> 
 
 You can name these files `whatever_you_want.yml`, and nest them arbitrarily deeply in subfolders within the `analyses/` or `models/` directory.
 

website/docs/reference/configs-and-properties.md

@@ -64,15 +64,18 @@ Previous versions of the docs referred to these as `schema.yml` files — we've
 
 ### Which properties are _not_ also configs?
 
-dbt has the ability to define node configs in `.yml` files, in addition to `config()` blocks and `dbt_project.yml`. But the reverse isn't always true: there are some things in `.yml` files that can _only_ be defined there.
+In dbt, you can define node configs in `.yml` files, in addition to `config()` blocks and `dbt_project.yml`. However, some properties are exclusive to `.yml` files. 
+
 
 Certain properties are special, because:
+
 - They have a unique Jinja rendering context
 - They create new project resources
 - They don't make sense as hierarchical configuration
 - They're older properties that haven't yet been redefined as configs
 
-These properties are:
+This means "configs" can be set for multiple resources at once in the `dbt_project.yml` file, while "properties" can only be set for one resource at a time. The following properties _cannot_ be configured from `dbt_project.yml`:
+
 - [`description`](/reference/resource-properties/description)
 - [`tests`](/reference/resource-properties/tests)
 - [`docs`](/reference/resource-configs/docs)

website/docs/reference/dbt_project.yml.md

@@ -4,7 +4,7 @@
 
 </Changelog>
 
-Every [dbt project](/docs/build/projects) needs a `dbt_project.yml` file — this is how dbt knows a directory is a dbt project. It also contains important information that tells dbt how to operate on your project.
+Every [dbt project](/docs/build/projects) needs a `dbt_project.yml` file — this is how dbt knows a directory is a dbt project. It also contains important information that tells dbt how to operate your project.
 
 <VersionBlock lastVersion="1.4">
 
@@ -18,12 +18,37 @@ By default, dbt will look for `dbt_project.yml` in your current working director
 
 </VersionBlock>
 
-The following is a list of all available configurations in the `dbt_project.yml` file.
-
 :::info YAML syntax
-dbt uses YAML in a few different places. If you're new to YAML, it would be worth taking the time to learn how arrays, dictionaries and strings are represented.
+
+dbt uses YAML in a few different places. If you're new to YAML, it would be worth taking the time to learn how arrays, dictionaries, and strings are represented.
 :::
 
+
+<VersionBlock firstVersion="1.7">
+
+Something to note, the following properties _aren't_ supported in in the `dbt_project.yml` file:
+
+- [Exposure properties](/reference/exposure-properties)
+- [Macro properties](/reference/macro-properties)
+- [Analysis properties](/reference/analysis-properties)
+- [Source properties](/reference/source-properties)
+
+</VersionBlock>
+
+<VersionBlock lastVersion="1.6">
+
+Something to note, the following properties _aren't_ supported in in the `dbt_project.yml` file:
+
+- [Exposure properties](/reference/exposure-properties)
+- [Macro properties](/reference/macro-properties)
+- [Analysis properties](/reference/analysis-properties)
+- [Semantic model configs](/docs/build/semantic-models)
+- [Source properties](/reference/source-properties)
+
+</VersionBlock>
+
+The following example is a list of all available configurations in the `dbt_project.yml` file:
+
 <File name='dbt_project.yml'>
 
 ```yml

website/docs/reference/exposure-properties.md

@@ -8,7 +8,11 @@ description: "Read this guide to understand exposure properties in dbt."
 - [Declaring resource properties](/reference/configs-and-properties)
 
 ## Overview
-Exposures are defined in `.yml` files nested under an `exposures:` key. You may define `exposures` in YAML files that also define define `sources` or `models`.
+
+import PropsCallout from '/snippets/_config-prop-callout.md';
+
+Exposures are defined in `.yml` files nested under an `exposures:` key. You may define `exposures` in YAML files that also define `sources` or `models`, _except_ in the `dbt_project.yml` file. <PropsCallout title={frontMatter.title}/>  <br /> 
+
 
 You can name these files `whatever_you_want.yml`, and nest them arbitrarily deeply in subfolders within the `models/` directory.
 

website/docs/reference/macro-properties.md

@@ -1,10 +1,13 @@
 ---
 title: Macro properties
+id: macro-properties
 ---
 
-Macro properties can be declared in `.yml` files.
+import PropsCallout from '/snippets/_config-prop-callout.md';
 
-You can name these files `whatever_you_want.yml`, and nest them arbitrarily deeply in subfolders.
+Macro properties can be declared in any `.yml` file, except for the `dbt_project.yml` file. <PropsCallout title={frontMatter.title}/> 
+
+You can name these files `whatever_you_want.yml` and nest them arbitrarily deep in sub-folders.
 
 <File name='macros/<filename>.yml'>
 

website/docs/reference/resource-configs/docs.md

@@ -17,18 +17,35 @@ default_value: {show: true}
     { label: 'Macros', value: 'macros', },
   ]
 }>
+
 <TabItem value="models">
 
+You can use the docs property in YAML files, including the `dbt_project.yml`:
+
+<File name='dbt_project.yml'>
+
+```yml
+name: "your_dbt_project_name"
+version: "1.0.0"
+config-version: 2
+
+models:
+  - name: model_name
+    docs:
+      show: true | false
+```
+</File>
+
 <File name='models/schema.yml'>
 
+
 ```yml
 version: 2
 
 models:
   - name: model_name
     docs:
       show: true | false
-
 ```
 
 </File>
@@ -43,6 +60,22 @@ This property is not implemented for sources.
 
 <TabItem value="seeds">
 
+You can use the docs property in YAML files, including the `dbt_project.yml`:
+
+<File name='dbt_project.yml'>
+
+```yml
+name: "your_dbt_project_name"
+version: "1.0.0"
+config-version: 2
+
+seeds:
+  - name: seed_name
+    docs:
+      show: true | false
+```
+</File>
+
 <File name='seeds/schema.yml'>
 
 ```yml
@@ -52,15 +85,29 @@ seeds:
   - name: seed_name
     docs:
       show: true | false
-
 ```
-
 </File>
 
 </TabItem>
 
 <TabItem value="snapshots">
 
+You can use the docs property in YAML files, including the `dbt_project.yml`:
+
+<File name='dbt_project.yml'>
+
+```yml
+name: "your_dbt_project_name"
+version: "1.0.0"
+config-version: 2
+
+snapshots:
+  - name: snapshot_name
+    docs:
+      show: true | false
+```
+</File>
+
 <File name='snapshots/schema.yml'>
 
 ```yml
@@ -70,15 +117,29 @@ snapshots:
   - name: snapshot_name
     docs:
       show: true | false
-
 ```
-
 </File>
 
 </TabItem>
 
 <TabItem value="analyses">
 
+You can use the docs property in YAML files, including the `dbt_project.yml`:
+
+<File name='dbt_project.yml'>
+
+```yml
+name: "your_dbt_project_name"
+version: "1.0.0"
+config-version: 2
+
+analyses:
+  - name: analysis_name
+    docs:
+      show: true | false
+```
+</File>
+
 <File name='analysis/schema.yml'>
 
 ```yml
@@ -89,16 +150,13 @@ analyses:
     docs:
       show: true | false
 ```
-
 </File>
 
 </TabItem>
 
 <TabItem value="macros">
 
-<!----
-To-do: check this
---->
+You can use the docs property in YAML files, _except_ in `dbt_project.yml`. [Macro properties](/reference/macro-properties) _are not_ supported in the `dbt_project.yml` file. 
 
 <File name='macros/schema.yml'>
 
@@ -109,9 +167,7 @@ macros:
   - name: macro_name
     docs:
       show: true | false
-
 ```
-
 </File>
 
 </TabItem>

website/docs/reference/source-properties.md

@@ -1,5 +1,5 @@
 ---
-title: "About source properties"
+title: "Source properties"
 description: "Learn how to use source properties in dbt."
 ---
 
@@ -8,9 +8,13 @@ description: "Learn how to use source properties in dbt."
 - [Declaring resource properties](/reference/configs-and-properties)
 
 ## Overview
-Source properties can be declared in `.yml` files in your `models/` directory (as defined by the [`model-paths` config](/reference/project-configs/model-paths)).
 
-You can name these files `whatever_you_want.yml`, and nest them arbitrarily deeply in subfolders within the `models/` directory.
+import PropsCallout from '/snippets/_config-prop-callout.md';
+
+Source properties can be declared in any `.yml` file in your `models/` directory (as defined by the [`model-paths` config](/reference/project-configs/model-paths)), except for the `dbt_project.yml` file. <PropsCallout title={frontMatter.title}/>  <br /> 
+
+
+You can name these files `whatever_you_want.yml`, and nest them arbitrarily deeply in subfolders within the `models/` directory:
 
 <File name='models/<filename>.yml'>
 

website/snippets/_config-prop-callout.md

@@ -0,0 +1 @@
+<span>This is because you can set "configs" for many resources in <code>dbt_project.yml</code>, while you can only set "properties" one resource at a time. Since {props.title} are "properties", this means you cannot configure it from <code>dbt_project.yml</code></span>.  Refer to <a href="https://docs.getdbt.com/reference/configs-and-properties#which-properties-are-not-also-configs" target="_self"> Configs and properties</a> for more info.