add new spec to references pages

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

@@ -26,9 +26,18 @@ Whereas you can use **configurations** to:
 
 Depending on the resource type, configurations can be defined in the dbt project and also in an installed package by:
 
+<VersionBlock firstVersion="1.9">
+
+1. Using a [`config` property](/reference/resource-properties/config) in a `.yml` file in the `models/`, `snapshots/`, `seeds/`, `analyses`, or `tests/` directory
+2. From the [`dbt_project.yml` file](dbt_project.yml), under the corresponding resource key (`models:`, `snapshots:`, `tests:`, etc)
+</VersionBlock>
+
+<VersionBlock lastVersion="1.8">
+
 1. Using a [`config()` Jinja macro](/reference/dbt-jinja-functions/config) within a `model`, `snapshot`, or `test` SQL file
-2. Using a [`config` property](/reference/resource-properties/config) in a `.yml` file
+2. Using a [`config` property](/reference/resource-properties/config) in a `.yml` file in the `models/`, `snapshots/`, `seeds/`, `analyses/`, or `tests/` directory.
 3. From the [`dbt_project.yml` file](dbt_project.yml), under the corresponding resource key (`models:`, `snapshots:`, `tests:`, etc)
+</VersionBlock>
 
 ### Config inheritance
 

website/docs/reference/project-configs/snapshot-paths.md

@@ -12,7 +12,16 @@ snapshot-paths: [directorypath]
 </File>
 
 ## Definition
-Optionally specify a custom list of directories where [snapshots](/docs/build/snapshots) are located. Note that you cannot co-locate models and snapshots.
+
+Optionally specify a custom list of directories where [snapshots](/docs/build/snapshots) are located. 
+
+<VersionBlock firstVersion="1.9">
+In [Versionless](/docs/dbt-versions/versionless-cloud) and on dbt v1.9 and higher, you can co-locate your snapshots with models if they are [defined using the latest YAML syntax](/docs/build/snapshots). 
+</VersionBlock>
+
+<VersionBlock lastVersion="1.8">
+Note that you cannot co-locate models and snapshots. However, in [Versionless](/docs/dbt-versions/versionless-cloud) and on dbt v1.9 and higher, you can co-locate your snapshots with models if they are [defined using the latest YAML syntax](/docs/build/snapshots).
+</VersionBlock>
 
 ## Default
 By default, dbt will search for snapshots in the `snapshots` directory, i.e. `snapshot-paths: ["snapshots"]`

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

@@ -3,6 +3,32 @@ resource_types: [snapshots]
 description: "Read this guide to understand the check_cols configuration in dbt."
 datatype: "[column_name] | all"
 ---
+
+<VersionBlock firstVersion="1.9">
+<File name="snapshots/<filename>.yml">
+
+  ```yml
+  snapshots:
+  - name: snapshot_name
+    relation: source('my_source', 'my_table')
+    config:
+      schema: string
+      unique_key: column_name_or_expression
+      strategy: check
+      check_cols:
+        - column_name
+  ```
+
+</File>
+</VersionBlock>
+
+<VersionBlock lastVersion="1.8">
+
+:::info Use the latest snapshot syntax
+
+In Versionless and dbt v1.9 and later, snapshots are defined in an updated syntax using a YAML file within your `snapshots/` directory (as defined by the [`snapshot-paths` config](/reference/project-configs/snapshot-paths)). For faster and more efficient management, consider the updated snapshot YAML syntax, [available in Versionless](/docs/dbt-versions/versionless-cloud) or [dbt Core v1.9 and later](/docs/dbt-versions/core).
+:::
+
 <File name='snapshots/<filename>.sql'>
 
 ```jinja2
@@ -14,7 +40,7 @@ datatype: "[column_name] | all"
 ```
 
 </File>
-
+</VersionBlock>
 
 <File name='dbt_project.yml'>
 
@@ -42,6 +68,29 @@ No default is provided.
 
 ### Check a list of columns for changes
 
+<VersionBlock firstVersion="1.9">
+
+<File name="snapshots/orders_snapshot_check.yml">
+
+```yaml
+snapshots:
+  - name: orders_snapshot_check
+    relation: source('jaffle_shop', 'orders')
+    config:
+      schema: snapshots
+      unique_key: id
+      strategy: check
+      check_cols:
+        - status
+        - is_cancelled
+```
+</File>
+
+To select from this snapshot in a downstream model: `select * from {{ source('jaffle_shop', 'orders') }}`
+</VersionBlock>
+
+<VersionBlock lastVersion="1.8">
+
 ```sql
 {% snapshot orders_snapshot_check %}
 
@@ -58,8 +107,32 @@ No default is provided.
 {% endsnapshot %}
 ```
 
+</VersionBlock>
+
 ### Check all columns for changes
 
+<VersionBlock firstVersion="1.9">
+
+<File name="orders_snapshot_check.yml">
+
+```yaml
+snapshots:
+  - name: orders_snapshot_check
+    relation: source('jaffle_shop', 'orders')
+    config:
+      schema: snapshots
+      unique_key: id
+      strategy: check
+      check_cols:
+        - all
+  ```
+</File>
+
+To select from this snapshot in a downstream model: `select * from {{ source('jaffle_shop', 'orders') }}`
+</VersionBlock>
+
+<VersionBlock lastVersion="1.8">
+
 ```sql
 {% snapshot orders_snapshot_check %}
 
@@ -75,3 +148,4 @@ No default is provided.
 
 {% endsnapshot %}
 ```
+</VersionBlock>

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

@@ -4,6 +4,32 @@ description: "Invalidate_hard_deletes - Read this in-depth guide to learn about
 datatype: column_name
 ---
 
+
+<VersionBlock firstVersion="1.9">
+
+<File name='snapshots/<filename>.yml'>
+
+```yaml
+snapshots:
+  - name: snapshot
+    relation: source('my_source', 'my_table')
+    [config](/reference/snapshot-configs):
+      strategy: timestamp
+      invalidate_hard_deletes: true | false
+```
+
+</File>
+
+
+</VersionBlock>
+
+<VersionBlock lastVersion="1.8">
+
+:::info Use the latest snapshot syntax
+
+In Versionless and dbt v1.9 and later, snapshots are defined in an updated syntax using a YAML file within your `snapshots/` directory (as defined by the [`snapshot-paths` config](/reference/project-configs/snapshot-paths)). For faster and more efficient management, consider the updated snapshot YAML syntax, [available in Versionless](/docs/dbt-versions/versionless-cloud) or [dbt Core v1.9 and later](/docs/dbt-versions/core).
+:::
+
 <File name='snapshots/<filename>.sql'>
 
 ```jinja2
@@ -17,6 +43,7 @@ datatype: column_name
 ```
 
 </File>
+</VersionBlock>
 
 <File name='dbt_project.yml'>
 
@@ -39,6 +66,26 @@ By default the feature is disabled.
 
 ## Example
 
+<VersionBlock firstVersion="1.9">
+<File name='snapshots/orders.yml'>
+
+```yaml
+snapshots:
+  - name: orders_snapshot
+    relation: source('jaffle_shop', 'orders')
+    config:
+      schema: snapshots
+      database: analytics
+      unique_key: id
+      strategy: timestamp
+      updated_at: updated_at
+      invalidate_hard_deletes: true
+  ```
+</File>
+
+</VersionBlock>
+
+<VersionBlock lastVersion="1.8">
 <File name='snapshots/orders.sql'>
 
 ```sql
@@ -60,3 +107,4 @@ By default the feature is disabled.
 ```
 
 </File>
+</VersionBlock>

website/docs/reference/resource-configs/pre-hook-post-hook.md

@@ -109,6 +109,8 @@ snapshots:
 
 </File>
 
+<VersionBlock lastVersion="1.8">
+
 <File name='snapshots/<filename>.sql'>
 
 ```sql
@@ -125,13 +127,15 @@ select ...
 ```
 
 </File>
+</VersionBlock>
 
-<File name='snapshots/properties.yml'>
+<File name='snapshots/snapshot.yml'>
 
 ```yml
 snapshots:
   - name: [<snapshot_name>]
-    config:
+    [config](/reference/resource-properties/config):
+      [<snapshot_config>](/reference/snapshot-configs): <config_value>
       [pre_hook](/reference/resource-configs/pre-hook-post-hook): <sql-statement> | [<sql-statement>]
       [post_hook](/reference/resource-configs/pre-hook-post-hook): <sql-statement> | [<sql-statement>]
 ```

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

@@ -2,6 +2,27 @@
 description: "Snapshot-name - Read this in-depth guide to learn about configurations in dbt."
 ---
 
+<VersionBlock firstVersion="1.9">
+<File name='snapshots/<filename>.yml'>
+
+```yaml
+snapshots:
+  - name: snapshot_name
+    relation: source('my_source', 'my_table')
+    config:
+      schema: string
+      database: string
+      unique_key: column_name_or_expression
+      strategy: timestamp | check
+      updated_at: column_name  # Required if strategy is 'timestamp'
+
+```
+
+</File>
+</VersionBlock>
+
+<VersionBlock lastVersion="1.8">
+
 <File name='snapshots/<filename>.sql'>
 
 ```jinja2
@@ -13,9 +34,16 @@ description: "Snapshot-name - Read this in-depth guide to learn about configurat
 
 </File>
 
+:::info Use the latest snapshot syntax
+
+In Versionless and dbt v1.9 and later, snapshots are defined in an updated syntax using a YAML file within your `snapshots/` directory (as defined by the [`snapshot-paths` config](/reference/project-configs/snapshot-paths)). For faster and more efficient management, consider the updated snapshot YAML syntax, [available in Versionless](/docs/dbt-versions/versionless-cloud) or [dbt Core v1.9 and later](/docs/dbt-versions/core).
+:::
+
+</VersionBlock>
+
 ## Description
 
-The name of a snapshot, as defined in the `{% snapshot %}` block header. This name is used when selecting from a snapshot using the [`ref` function](/reference/dbt-jinja-functions/ref)
+The name of a snapshot, which is used when selecting from a snapshot using the [`ref` function](/reference/dbt-jinja-functions/ref)
 
 This name must not conflict with the name of any other "refable" resource (models, seeds, other snapshots) defined in this project or package.
 
@@ -24,6 +52,26 @@ The name does not need to match the file name. As a result, snapshot filenames d
 ## Examples
 ### Name a snapshot `order_snapshot`
 
+<VersionBlock firstVersion="1.9">
+<File name='snapshots/order_snapshot.yml'>
+
+
+```yaml
+snapshots:
+  - name: order_snapshot
+    relation: source('my_source', 'my_table')
+    config:
+      schema: string
+      database: string
+      unique_key: column_name_or_expression
+      strategy: timestamp | check
+      updated_at: column_name  # Required if strategy is 'timestamp'
+```
+</File>
+
+</VersionBlock>
+
+<VersionBlock lastVersion="1.8">
 <File name='snapshots/orders.sql'>
 
 ```jinja2
@@ -35,6 +83,7 @@ The name does not need to match the file name. As a result, snapshot filenames d
 
 </File>
 
+</VersionBlock>
 
 To select from this snapshot in a downstream model: