diff --git a/docs/data-sources/dns_zone.md b/docs/data-sources/dns_zone.md
index f1405fc..818b698 100644
--- a/docs/data-sources/dns_zone.md
+++ b/docs/data-sources/dns_zone.md
@@ -10,7 +10,14 @@ description: |-
 
 
 
-
+## Example Usage
+
+```terraform
+# Read-only data source for a Netlify DNS zone.
+data "netlify_dns_zone" "example" {
+  name = "example.com"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
diff --git a/docs/data-sources/site.md b/docs/data-sources/site.md
index 8744965..3b58707 100644
--- a/docs/data-sources/site.md
+++ b/docs/data-sources/site.md
@@ -10,7 +10,20 @@ description: |-
 
 
 
-
+## Example Usage
+
+```terraform
+# Looking up a site by its team slug and site name
+data "netlify_site" "blog" {
+  team_slug = "my-team-slug"
+  name      = "Blog"
+}
+
+# Looking up a blog by its ID
+data "netlify_site" "blog" {
+  id = "12345667-0000-0000-0000-abcdef012345"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
diff --git a/docs/data-sources/sites.md b/docs/data-sources/sites.md
index 5dad9a0..a860de3 100644
--- a/docs/data-sources/sites.md
+++ b/docs/data-sources/sites.md
@@ -10,7 +10,14 @@ description: |-
 
 
 
-
+## Example Usage
+
+```terraform
+# List all sites in a team, by the team's slug
+data "netlify_sites" "team" {
+  team_slug = "my-team-slug"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
diff --git a/docs/data-sources/team.md b/docs/data-sources/team.md
index 5041354..5736dd1 100644
--- a/docs/data-sources/team.md
+++ b/docs/data-sources/team.md
@@ -10,7 +10,19 @@ description: |-
 
 
 
-
+## Example Usage
+
+```terraform
+# Looking up a team by its slug
+data "netlify_team" "team" {
+  slug = "my-team-slug"
+}
+
+# Looking up a team by its ID
+data "netlify_team" "team" {
+  id = "6600abcdef1234567890abcd"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
diff --git a/docs/index.md b/docs/index.md
index befd341..5f21b6f 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -7,7 +7,70 @@ description: |-
 
 # Netlify Provider
 
-The Netlify provider provides resources to interact with a Netlify account.
+The Netlify provider provides resources to manage Netlify resources like site configuration, environment variables, and Advanced Web Security features.
+
+## Authentication
+
+To use the provider, you will need a [personal access token](https://docs.netlify.com/api/get-started/#authentication).
+You can create a new token in the [Netlify app](https://app.netlify.com/user/applications#personal-access-tokens).
+
+You can expose the token as an environment variable:
+```bash
+export NETLIFY_API_TOKEN="your-personal-access-token"
+```
+
+Or by creating a Terraform variable:
+```terraform
+variable "netlify_api_token" {
+  type = string
+}
+
+provider "netlify" {
+  token = var.netlify_api_token
+}
+```
+and setting the variable's value as an environment variable (`TF_VAR_netlify_api_token`).
+
+## Example Usage
+
+```terraform
+variable "netlify_api_token" {
+  type = string
+}
+
+terraform {
+  required_providers {
+    netlify = {
+      source = "registry.terraform.io/netlify/netlify"
+    }
+  }
+}
+
+provider "netlify" {
+  token = var.netlify_api_token
+}
+
+data "netlify_team" "team" {
+  slug = "your-team-slug"
+}
+
+data "netlify_site" "blog" {
+  team_slug = data.netlify_team.team.slug
+  name      = "blog"
+}
+
+resource "netlify_environment_variable" "astro_database_file" {
+  team_id = data.netlify_team.team.id
+  site_id = data.netlify_site.blog.id
+  key     = "ASTRO_DATABASE_FILE"
+  values = [
+    {
+      value   = "/path/here",
+      context = "all",
+    }
+  ]
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -15,4 +78,4 @@ The Netlify provider provides resources to interact with a Netlify account.
 ### Optional
 
 - `endpoint` (String) Defaults to: https://api.netlify.com
-- `token` (String, Sensitive) Read: https://docs.netlify.com/api/get-started/
+- `token` (String, Sensitive) Read: https://docs.netlify.com/api/get-started/#authentication , will use the `NETLIFY_API_TOKEN` environment variable if not set.
diff --git a/docs/resources/dns_record.md b/docs/resources/dns_record.md
index 840e3f7..1796775 100644
--- a/docs/resources/dns_record.md
+++ b/docs/resources/dns_record.md
@@ -3,22 +3,46 @@
 page_title: "netlify_dns_record Resource - netlify"
 subcategory: ""
 description: |-
-  
+  Netlify DNS record. Read more https://docs.netlify.com/domains-https/netlify-dns/
 ---
 
 # netlify_dns_record (Resource)
 
+Netlify DNS record. [Read more](https://docs.netlify.com/domains-https/netlify-dns/)
 
+## Example Usage
 
+```terraform
+resource "netlify_dns_record" "www" {
+  type     = "A"
+  zone_id  = netlify_dns_zone.example.id
+  hostname = "www.example.com"
+  value    = "198.18.0.50"
+}
 
+resource "netlify_dns_record" "calendar" {
+  type     = "CNAME"
+  zone_id  = netlify_dns_zone.example.id
+  hostname = "calendar.example.com"
+  value    = "ghs.googlehosted.com."
+}
+
+resource "netlify_dns_record" "mx" {
+  type     = "MX"
+  zone_id  = netlify_dns_zone.example.id
+  hostname = "example.com"
+  value    = "smtp.google.com"
+  priority = 1
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `hostname` (String)
-- `type` (String)
+- `hostname` (String) The hostname for the DNS record. For example, `www.example.com`.
+- `type` (String) One of A, AAAA, ALIAS, CAA, CNAME, MX, NS, SPF, or TXT
 - `value` (String)
 - `zone_id` (String)
 
@@ -33,3 +57,12 @@ description: |-
 
 - `id` (String) The ID of this resource.
 - `last_updated` (String)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# Import a DNS record by its zone ID and its record ID
+terraform import netlify_dns_record.www_example 6600abcdef1234567890abcd:6600abcdef1234567890abcd
+```
diff --git a/docs/resources/dns_zone.md b/docs/resources/dns_zone.md
index f22afcf..0aecbda 100644
--- a/docs/resources/dns_zone.md
+++ b/docs/resources/dns_zone.md
@@ -3,14 +3,24 @@
 page_title: "netlify_dns_zone Resource - netlify"
 subcategory: ""
 description: |-
-  
+  Netlify DNS zone. Read more https://docs.netlify.com/domains-https/netlify-dns/
 ---
 
 # netlify_dns_zone (Resource)
 
+Netlify DNS zone. [Read more](https://docs.netlify.com/domains-https/netlify-dns/)
 
+## Example Usage
 
-
+```terraform
+resource "netlify_dns_zone" "example" {
+  team_slug = data.netlify_team.team.slug
+  name      = "example.com"
+  lifecycle {
+    prevent_destroy = true
+  }
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -40,3 +50,12 @@ Read-Only:
 - `name` (String)
 - `registered_at` (String)
 - `renewal_price` (String)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# Import a DNS zone by its ID
+terraform import netlify_dns_zone.example 6600abcdef1234567890abcd
+```
diff --git a/docs/resources/environment_variable.md b/docs/resources/environment_variable.md
index e364ef5..40e07d4 100644
--- a/docs/resources/environment_variable.md
+++ b/docs/resources/environment_variable.md
@@ -3,14 +3,87 @@
 page_title: "netlify_environment_variable Resource - netlify"
 subcategory: ""
 description: |-
-  
+  Environment variables for Netlify sites. Read more https://docs.netlify.com/environment-variables/overview/
 ---
 
 # netlify_environment_variable (Resource)
 
-
-
-
+Environment variables for Netlify sites. [Read more](https://docs.netlify.com/environment-variables/overview/)
+
+## Example Usage
+
+```terraform
+# Site-level environment variable, note that both team_id and site_id are specified
+resource "netlify_environment_variable" "astro_database_file" {
+  team_id = data.netlify_team.team.id
+  site_id = data.netlify_site.blog.id
+  key     = "ASTRO_DATABASE_FILE"
+  values = [
+    {
+      value   = "/path/here",
+      context = "all",
+    }
+  ]
+}
+
+# Team-level environment variable, note that only team_id is specified
+# Not supported on all Netlify plans
+resource "netlify_environment_variable" "astro_database_file" {
+  team_id = data.netlify_team.team.id
+  key     = "ASTRO_DATABASE_FILE"
+  values = [
+    {
+      value   = "/path/here",
+      context = "all",
+    }
+  ]
+}
+
+# Secret environment variable
+# Not supported on all Netlify plans
+resource "netlify_environment_variable" "astro_studio_app_token" {
+  team_id = data.netlify_team.team.id
+  site_id = data.netlify_site.blog.id
+  key     = "ASTRO_STUDIO_APP_TOKEN"
+  secret_values = [
+    {
+      value   = "token-here",
+      context = "all",
+    }
+  ]
+}
+
+# Values that differ by context
+resource "netlify_environment_variable" "astro_studio_app_token" {
+  team_id = data.netlify_team.team.id
+  site_id = data.netlify_site.blog.id
+  key     = "ASTRO_STUDIO_APP_TOKEN"
+  secret_values = [
+    {
+      value   = "token-here",
+      context = "production",
+    },
+    {
+      value   = "non-prod-token-here",
+      context = "deploy-preview",
+    }
+  ]
+}
+
+# A variable that's only available in some scopes, e.g. in builds
+resource "netlify_environment_variable" "astro_database_file" {
+  team_id = data.netlify_team.team.id
+  site_id = data.netlify_site.blog.id
+  key     = "ASTRO_DATABASE_FILE"
+  scopes  = ["builds"]
+  values = [
+    {
+      value   = "/path/here",
+      context = "all",
+    }
+  ]
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -22,7 +95,7 @@ description: |-
 
 ### Optional
 
-- `scopes` (Set of String)
+- `scopes` (Set of String) One or more of builds, functions, runtime, and post-processing
 - `secret_values` (Attributes Set) (see [below for nested schema](#nestedatt--secret_values))
 - `site_id` (String)
 - `values` (Attributes Set) (see [below for nested schema](#nestedatt--values))
@@ -36,7 +109,7 @@ description: |-
 
 Required:
 
-- `context` (String)
+- `context` (String) One of all, dev, branch-deploy, deploy-preview, production, or branch
 - `value` (String, Sensitive)
 
 Optional:
@@ -49,9 +122,21 @@ Optional:
 
 Required:
 
-- `context` (String)
+- `context` (String) One of all, dev, branch-deploy, deploy-preview, production, or branch
 - `value` (String)
 
 Optional:
 
 - `context_parameter` (String)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# Import a team-level environment variable using the team ID and the environment variable key
+terraform import netlify_environment_variable.name 6600abcdef1234567890abcd:ASTRO_DATABASE_FILE
+
+# Import a site-level environment variable using the team ID, the site ID, and the environment variable key
+terraform import netlify_environment_variable.name 6600abcdef1234567890abcd:12345667-0000-0000-0000-abcdef012345:ASTRO_DATABASE_FILE
+```
diff --git a/docs/resources/log_drain.md b/docs/resources/log_drain.md
index 197a25f..e465541 100644
--- a/docs/resources/log_drain.md
+++ b/docs/resources/log_drain.md
@@ -3,29 +3,42 @@
 page_title: "netlify_log_drain Resource - netlify"
 subcategory: ""
 description: |-
-  
+  Netlify log drain. Read more https://docs.netlify.com/monitor-sites/log-drains/
 ---
 
 # netlify_log_drain (Resource)
 
+Netlify log drain. [Read more](https://docs.netlify.com/monitor-sites/log-drains/)
 
+## Example Usage
 
-
+```terraform
+resource "netlify_log_drain" "blog" {
+  site_id     = data.netlify_site.blog.id
+  destination = "http"
+  log_types   = ["user_traffic", "deploys", "edge_functions", "functions"]
+  format      = "ndjson"
+  exclude_pii = true
+  service_config = {
+    url = "https://destinationurl/"
+  }
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
 
 ### Required
 
-- `destination` (String)
+- `destination` (String) One of datadog, newrelic, logflare, s3, splunkcloud, http, axiom, or azure
 - `exclude_pii` (Boolean)
-- `log_types` (Set of String)
+- `log_types` (Set of String) One or more of user_traffic, functions, edge_functions, and deploys
 - `service_config` (Attributes) (see [below for nested schema](#nestedatt--service_config))
 - `site_id` (String)
 
 ### Optional
 
-- `format` (String)
+- `format` (String) json or ndjson
 
 ### Read-Only
 
@@ -45,3 +58,12 @@ Optional:
 - `tags` (Map of String)
 - `url` (String, Sensitive)
 - `verification_filename` (String)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# Import a log drain by its site ID and the log drain ID
+terraform import netlify_log_drain.http 12345667-0000-0000-0000-abcdef012345:12345667-0000-0000-0000-abcdef012345
+```
diff --git a/docs/resources/site_build_settings.md b/docs/resources/site_build_settings.md
index d3afa55..6048479 100644
--- a/docs/resources/site_build_settings.md
+++ b/docs/resources/site_build_settings.md
@@ -10,7 +10,17 @@ description: |-
 
 
 
-
+## Example Usage
+
+```terraform
+resource "netlify_site_build_settings" "blog" {
+  site_id                = data.netlify_site.blog.id
+  build_command          = "npm run build"
+  publish_directory      = "dist"
+  production_branch      = "main"
+  branch_deploy_branches = ["preview", "staging"]
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -38,3 +48,12 @@ description: |-
 ### Read-Only
 
 - `last_updated` (String)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# Import a site's domain settings by the site ID
+terraform import netlify_site_domain_settings.blog 12345667-0000-0000-0000-abcdef012345
+```
diff --git a/docs/resources/site_collaboration_settings.md b/docs/resources/site_collaboration_settings.md
index e68c1b5..0a10a9e 100644
--- a/docs/resources/site_collaboration_settings.md
+++ b/docs/resources/site_collaboration_settings.md
@@ -10,7 +10,16 @@ description: |-
 
 
 
+## Example Usage
 
+```terraform
+resource "netlify_site_collaboration_settings" "blog" {
+  site_id                           = data.netlify_site.blog.id
+  netlify_drawer_in_deploy_previews = true
+  netlify_drawer_in_branch_deploys  = true
+  netlify_heads_up_display          = true
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -25,3 +34,12 @@ description: |-
 ### Read-Only
 
 - `last_updated` (String)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# Import a site's collaboration settings by the site ID
+terraform import netlify_site_collaboration_settings.blog 12345667-0000-0000-0000-abcdef012345
+```
diff --git a/docs/resources/site_domain_settings.md b/docs/resources/site_domain_settings.md
index 1eb03ed..d3a3aa9 100644
--- a/docs/resources/site_domain_settings.md
+++ b/docs/resources/site_domain_settings.md
@@ -10,7 +10,17 @@ description: |-
 
 
 
-
+## Example Usage
+
+```terraform
+resource "netlify_site_domain_settings" "blog" {
+  site_id                      = data.netlify_site.blog.id
+  custom_domain                = "blog.example.com"
+  domain_aliases               = ["blog-alias.example.com"]
+  branch_deploy_custom_domain  = "blog-branch.example.com"
+  deploy_preview_custom_domain = "blog-dp.example.com"
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -29,3 +39,12 @@ description: |-
 ### Read-Only
 
 - `last_updated` (String)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# Import a site's domain settings by the site ID
+terraform import netlify_site_domain_settings.blog 12345667-0000-0000-0000-abcdef012345
+```
diff --git a/docs/resources/site_firewall_traffic_rules.md b/docs/resources/site_firewall_traffic_rules.md
index 2629e94..c9cba31 100644
--- a/docs/resources/site_firewall_traffic_rules.md
+++ b/docs/resources/site_firewall_traffic_rules.md
@@ -3,14 +3,47 @@
 page_title: "netlify_site_firewall_traffic_rules Resource - netlify"
 subcategory: ""
 description: |-
-  
+  Netlify site-level firewall traffic rules. Read more https://docs.netlify.com/security/secure-access-to-sites/traffic-rules/
 ---
 
 # netlify_site_firewall_traffic_rules (Resource)
 
-
-
-
+Netlify site-level firewall traffic rules. [Read more](https://docs.netlify.com/security/secure-access-to-sites/traffic-rules/)
+
+## Example Usage
+
+```terraform
+resource "netlify_site_firewall_traffic_rules" "blog" {
+  site_id = data.netlify_site.blog.id
+  published = {
+    default_action = "allow"
+    ip_restrictions = [
+      {
+        description = "bot network"
+        addresses = [
+          "192.0.2.0/24",
+          "198.51.100.0/24",
+        ]
+      }
+    ]
+    geo_exceptions = [
+      {
+        description = "brazil"
+        countries   = ["BR"]
+      }
+    ]
+  }
+  unpublished = {
+    default_action = "deny"
+    ip_exceptions = [
+      {
+        description = "Allow the VPN IP"
+        addresses   = ["203.0.113.65/32"]
+      }
+    ]
+  }
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -31,7 +64,7 @@ description: |-
 
 Required:
 
-- `default_action` (String)
+- `default_action` (String) One of allow or deny
 
 Optional:
 
@@ -90,7 +123,7 @@ Required:
 
 Required:
 
-- `default_action` (String)
+- `default_action` (String) One of allow or deny
 
 Optional:
 
@@ -141,3 +174,12 @@ Required:
 
 - `addresses` (List of String)
 - `description` (String)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# Import a site's firewall traffic rules by the site ID
+terraform import netlify_site_firewall_traffic_rules.blog 12345667-0000-0000-0000-abcdef012345
+```
diff --git a/docs/resources/team_firewall_traffic_rules.md b/docs/resources/team_firewall_traffic_rules.md
index 676dcdb..4d5425b 100644
--- a/docs/resources/team_firewall_traffic_rules.md
+++ b/docs/resources/team_firewall_traffic_rules.md
@@ -3,14 +3,47 @@
 page_title: "netlify_team_firewall_traffic_rules Resource - netlify"
 subcategory: ""
 description: |-
-  
+  Netlify team-level firewall traffic rules. Read more https://docs.netlify.com/security/secure-access-to-sites/traffic-rules/
 ---
 
 # netlify_team_firewall_traffic_rules (Resource)
 
-
-
-
+Netlify team-level firewall traffic rules. [Read more](https://docs.netlify.com/security/secure-access-to-sites/traffic-rules/)
+
+## Example Usage
+
+```terraform
+resource "netlify_team_firewall_traffic_rules" "team" {
+  site_id = data.netlify_team.team.id
+  published = {
+    default_action = "allow"
+    ip_restrictions = [
+      {
+        description = "bot network"
+        addresses = [
+          "192.0.2.0/24",
+          "198.51.100.0/24",
+        ]
+      }
+    ]
+    geo_exceptions = [
+      {
+        description = "brazil"
+        countries   = ["BR"]
+      }
+    ]
+  }
+  unpublished = {
+    default_action = "deny"
+    ip_exceptions = [
+      {
+        description = "Allow the VPN IP"
+        addresses   = ["203.0.113.65/32"]
+      }
+    ]
+  }
+}
+```
 
 <!-- schema generated by tfplugindocs -->
 ## Schema
@@ -31,7 +64,7 @@ description: |-
 
 Required:
 
-- `default_action` (String)
+- `default_action` (String) One of allow or deny
 
 Optional:
 
@@ -90,7 +123,7 @@ Required:
 
 Required:
 
-- `default_action` (String)
+- `default_action` (String) One of allow or deny
 
 Optional:
 
@@ -141,3 +174,12 @@ Required:
 
 - `addresses` (List of String)
 - `description` (String)
+
+## Import
+
+Import is supported using the following syntax:
+
+```shell
+# Import a team's firewall traffic rules by the team ID
+terraform import netlify_team_firewall_traffic_rules.team 6600abcdef1234567890abcd
+```
diff --git a/examples/data-sources/netlify_dns_zone/data-source.tf b/examples/data-sources/netlify_dns_zone/data-source.tf
new file mode 100644
index 0000000..2ca2195
--- /dev/null
+++ b/examples/data-sources/netlify_dns_zone/data-source.tf
@@ -0,0 +1,4 @@
+# Read-only data source for a Netlify DNS zone.
+data "netlify_dns_zone" "example" {
+  name = "example.com"
+}
diff --git a/examples/data-sources/netlify_site/data-source.tf b/examples/data-sources/netlify_site/data-source.tf
new file mode 100644
index 0000000..fd07648
--- /dev/null
+++ b/examples/data-sources/netlify_site/data-source.tf
@@ -0,0 +1,10 @@
+# Looking up a site by its team slug and site name
+data "netlify_site" "blog" {
+  team_slug = "my-team-slug"
+  name      = "Blog"
+}
+
+# Looking up a blog by its ID
+data "netlify_site" "blog" {
+  id = "12345667-0000-0000-0000-abcdef012345"
+}
diff --git a/examples/data-sources/netlify_sites/data-source.tf b/examples/data-sources/netlify_sites/data-source.tf
new file mode 100644
index 0000000..4694315
--- /dev/null
+++ b/examples/data-sources/netlify_sites/data-source.tf
@@ -0,0 +1,4 @@
+# List all sites in a team, by the team's slug
+data "netlify_sites" "team" {
+  team_slug = "my-team-slug"
+}
diff --git a/examples/data-sources/netlify_team/data-source.tf b/examples/data-sources/netlify_team/data-source.tf
new file mode 100644
index 0000000..bc3fd18
--- /dev/null
+++ b/examples/data-sources/netlify_team/data-source.tf
@@ -0,0 +1,9 @@
+# Looking up a team by its slug
+data "netlify_team" "team" {
+  slug = "my-team-slug"
+}
+
+# Looking up a team by its ID
+data "netlify_team" "team" {
+  id = "6600abcdef1234567890abcd"
+}
diff --git a/examples/dns/main.tf b/examples/misc/dns/main.tf
similarity index 100%
rename from examples/dns/main.tf
rename to examples/misc/dns/main.tf
diff --git a/examples/env_vars/main.tf b/examples/misc/env_vars/main.tf
similarity index 100%
rename from examples/env_vars/main.tf
rename to examples/misc/env_vars/main.tf
diff --git a/examples/firewall_traffic_rules/main.tf b/examples/misc/firewall_traffic_rules/main.tf
similarity index 100%
rename from examples/firewall_traffic_rules/main.tf
rename to examples/misc/firewall_traffic_rules/main.tf
diff --git a/examples/log_drains/main.tf b/examples/misc/log_drains/main.tf
similarity index 100%
rename from examples/log_drains/main.tf
rename to examples/misc/log_drains/main.tf
diff --git a/examples/site_data_sources/main.tf b/examples/misc/site_data_sources/main.tf
similarity index 100%
rename from examples/site_data_sources/main.tf
rename to examples/misc/site_data_sources/main.tf
diff --git a/examples/site_settings/main.tf b/examples/misc/site_settings/main.tf
similarity index 100%
rename from examples/site_settings/main.tf
rename to examples/misc/site_settings/main.tf
diff --git a/examples/provider/provider.tf b/examples/provider/provider.tf
new file mode 100644
index 0000000..69844c6
--- /dev/null
+++ b/examples/provider/provider.tf
@@ -0,0 +1,36 @@
+variable "netlify_api_token" {
+  type = string
+}
+
+terraform {
+  required_providers {
+    netlify = {
+      source = "registry.terraform.io/netlify/netlify"
+    }
+  }
+}
+
+provider "netlify" {
+  token = var.netlify_api_token
+}
+
+data "netlify_team" "team" {
+  slug = "your-team-slug"
+}
+
+data "netlify_site" "blog" {
+  team_slug = data.netlify_team.team.slug
+  name      = "blog"
+}
+
+resource "netlify_environment_variable" "astro_database_file" {
+  team_id = data.netlify_team.team.id
+  site_id = data.netlify_site.blog.id
+  key     = "ASTRO_DATABASE_FILE"
+  values = [
+    {
+      value   = "/path/here",
+      context = "all",
+    }
+  ]
+}
diff --git a/examples/resources/netlify_dns_record/import.sh b/examples/resources/netlify_dns_record/import.sh
new file mode 100644
index 0000000..92275e0
--- /dev/null
+++ b/examples/resources/netlify_dns_record/import.sh
@@ -0,0 +1,2 @@
+# Import a DNS record by its zone ID and its record ID
+terraform import netlify_dns_record.www_example 6600abcdef1234567890abcd:6600abcdef1234567890abcd
diff --git a/examples/resources/netlify_dns_record/resource.tf b/examples/resources/netlify_dns_record/resource.tf
new file mode 100644
index 0000000..323aa97
--- /dev/null
+++ b/examples/resources/netlify_dns_record/resource.tf
@@ -0,0 +1,21 @@
+resource "netlify_dns_record" "www" {
+  type     = "A"
+  zone_id  = netlify_dns_zone.example.id
+  hostname = "www.example.com"
+  value    = "198.18.0.50"
+}
+
+resource "netlify_dns_record" "calendar" {
+  type     = "CNAME"
+  zone_id  = netlify_dns_zone.example.id
+  hostname = "calendar.example.com"
+  value    = "ghs.googlehosted.com."
+}
+
+resource "netlify_dns_record" "mx" {
+  type     = "MX"
+  zone_id  = netlify_dns_zone.example.id
+  hostname = "example.com"
+  value    = "smtp.google.com"
+  priority = 1
+}
diff --git a/examples/resources/netlify_dns_zone/import.sh b/examples/resources/netlify_dns_zone/import.sh
new file mode 100644
index 0000000..4815556
--- /dev/null
+++ b/examples/resources/netlify_dns_zone/import.sh
@@ -0,0 +1,2 @@
+# Import a DNS zone by its ID
+terraform import netlify_dns_zone.example 6600abcdef1234567890abcd
diff --git a/examples/resources/netlify_dns_zone/resource.tf b/examples/resources/netlify_dns_zone/resource.tf
new file mode 100644
index 0000000..5957d91
--- /dev/null
+++ b/examples/resources/netlify_dns_zone/resource.tf
@@ -0,0 +1,7 @@
+resource "netlify_dns_zone" "example" {
+  team_slug = data.netlify_team.team.slug
+  name      = "example.com"
+  lifecycle {
+    prevent_destroy = true
+  }
+}
diff --git a/examples/resources/netlify_environment_variable/import.sh b/examples/resources/netlify_environment_variable/import.sh
new file mode 100644
index 0000000..3fa3586
--- /dev/null
+++ b/examples/resources/netlify_environment_variable/import.sh
@@ -0,0 +1,5 @@
+# Import a team-level environment variable using the team ID and the environment variable key
+terraform import netlify_environment_variable.name 6600abcdef1234567890abcd:ASTRO_DATABASE_FILE
+
+# Import a site-level environment variable using the team ID, the site ID, and the environment variable key
+terraform import netlify_environment_variable.name 6600abcdef1234567890abcd:12345667-0000-0000-0000-abcdef012345:ASTRO_DATABASE_FILE
diff --git a/examples/resources/netlify_environment_variable/resource.tf b/examples/resources/netlify_environment_variable/resource.tf
new file mode 100644
index 0000000..941b29c
--- /dev/null
+++ b/examples/resources/netlify_environment_variable/resource.tf
@@ -0,0 +1,70 @@
+# Site-level environment variable, note that both team_id and site_id are specified
+resource "netlify_environment_variable" "astro_database_file" {
+  team_id = data.netlify_team.team.id
+  site_id = data.netlify_site.blog.id
+  key     = "ASTRO_DATABASE_FILE"
+  values = [
+    {
+      value   = "/path/here",
+      context = "all",
+    }
+  ]
+}
+
+# Team-level environment variable, note that only team_id is specified
+# Not supported on all Netlify plans
+resource "netlify_environment_variable" "astro_database_file" {
+  team_id = data.netlify_team.team.id
+  key     = "ASTRO_DATABASE_FILE"
+  values = [
+    {
+      value   = "/path/here",
+      context = "all",
+    }
+  ]
+}
+
+# Secret environment variable
+# Not supported on all Netlify plans
+resource "netlify_environment_variable" "astro_studio_app_token" {
+  team_id = data.netlify_team.team.id
+  site_id = data.netlify_site.blog.id
+  key     = "ASTRO_STUDIO_APP_TOKEN"
+  secret_values = [
+    {
+      value   = "token-here",
+      context = "all",
+    }
+  ]
+}
+
+# Values that differ by context
+resource "netlify_environment_variable" "astro_studio_app_token" {
+  team_id = data.netlify_team.team.id
+  site_id = data.netlify_site.blog.id
+  key     = "ASTRO_STUDIO_APP_TOKEN"
+  secret_values = [
+    {
+      value   = "token-here",
+      context = "production",
+    },
+    {
+      value   = "non-prod-token-here",
+      context = "deploy-preview",
+    }
+  ]
+}
+
+# A variable that's only available in some scopes, e.g. in builds
+resource "netlify_environment_variable" "astro_database_file" {
+  team_id = data.netlify_team.team.id
+  site_id = data.netlify_site.blog.id
+  key     = "ASTRO_DATABASE_FILE"
+  scopes  = ["builds"]
+  values = [
+    {
+      value   = "/path/here",
+      context = "all",
+    }
+  ]
+}
diff --git a/examples/resources/netlify_log_drain/import.sh b/examples/resources/netlify_log_drain/import.sh
new file mode 100644
index 0000000..cc463ca
--- /dev/null
+++ b/examples/resources/netlify_log_drain/import.sh
@@ -0,0 +1,2 @@
+# Import a log drain by its site ID and the log drain ID
+terraform import netlify_log_drain.http 12345667-0000-0000-0000-abcdef012345:12345667-0000-0000-0000-abcdef012345
diff --git a/examples/resources/netlify_log_drain/resource.tf b/examples/resources/netlify_log_drain/resource.tf
new file mode 100644
index 0000000..31941f8
--- /dev/null
+++ b/examples/resources/netlify_log_drain/resource.tf
@@ -0,0 +1,10 @@
+resource "netlify_log_drain" "blog" {
+  site_id     = data.netlify_site.blog.id
+  destination = "http"
+  log_types   = ["user_traffic", "deploys", "edge_functions", "functions"]
+  format      = "ndjson"
+  exclude_pii = true
+  service_config = {
+    url = "https://destinationurl/"
+  }
+}
diff --git a/examples/resources/netlify_site_build_settings/import.sh b/examples/resources/netlify_site_build_settings/import.sh
new file mode 100644
index 0000000..060c6f8
--- /dev/null
+++ b/examples/resources/netlify_site_build_settings/import.sh
@@ -0,0 +1,2 @@
+# Import a site's domain settings by the site ID
+terraform import netlify_site_domain_settings.blog 12345667-0000-0000-0000-abcdef012345
diff --git a/examples/resources/netlify_site_build_settings/resource.tf b/examples/resources/netlify_site_build_settings/resource.tf
new file mode 100644
index 0000000..0edcb36
--- /dev/null
+++ b/examples/resources/netlify_site_build_settings/resource.tf
@@ -0,0 +1,7 @@
+resource "netlify_site_build_settings" "blog" {
+  site_id                = data.netlify_site.blog.id
+  build_command          = "npm run build"
+  publish_directory      = "dist"
+  production_branch      = "main"
+  branch_deploy_branches = ["preview", "staging"]
+}
diff --git a/examples/resources/netlify_site_collaboration_settings/import.sh b/examples/resources/netlify_site_collaboration_settings/import.sh
new file mode 100644
index 0000000..66c435e
--- /dev/null
+++ b/examples/resources/netlify_site_collaboration_settings/import.sh
@@ -0,0 +1,2 @@
+# Import a site's collaboration settings by the site ID
+terraform import netlify_site_collaboration_settings.blog 12345667-0000-0000-0000-abcdef012345
diff --git a/examples/resources/netlify_site_collaboration_settings/resource.tf b/examples/resources/netlify_site_collaboration_settings/resource.tf
new file mode 100644
index 0000000..5096bb9
--- /dev/null
+++ b/examples/resources/netlify_site_collaboration_settings/resource.tf
@@ -0,0 +1,6 @@
+resource "netlify_site_collaboration_settings" "blog" {
+  site_id                           = data.netlify_site.blog.id
+  netlify_drawer_in_deploy_previews = true
+  netlify_drawer_in_branch_deploys  = true
+  netlify_heads_up_display          = true
+}
diff --git a/examples/resources/netlify_site_domain_settings/import.sh b/examples/resources/netlify_site_domain_settings/import.sh
new file mode 100644
index 0000000..060c6f8
--- /dev/null
+++ b/examples/resources/netlify_site_domain_settings/import.sh
@@ -0,0 +1,2 @@
+# Import a site's domain settings by the site ID
+terraform import netlify_site_domain_settings.blog 12345667-0000-0000-0000-abcdef012345
diff --git a/examples/resources/netlify_site_domain_settings/resource.tf b/examples/resources/netlify_site_domain_settings/resource.tf
new file mode 100644
index 0000000..82d635f
--- /dev/null
+++ b/examples/resources/netlify_site_domain_settings/resource.tf
@@ -0,0 +1,7 @@
+resource "netlify_site_domain_settings" "blog" {
+  site_id                      = data.netlify_site.blog.id
+  custom_domain                = "blog.example.com"
+  domain_aliases               = ["blog-alias.example.com"]
+  branch_deploy_custom_domain  = "blog-branch.example.com"
+  deploy_preview_custom_domain = "blog-dp.example.com"
+}
diff --git a/examples/resources/netlify_site_firewall_traffic_rules/import.sh b/examples/resources/netlify_site_firewall_traffic_rules/import.sh
new file mode 100644
index 0000000..9811c08
--- /dev/null
+++ b/examples/resources/netlify_site_firewall_traffic_rules/import.sh
@@ -0,0 +1,2 @@
+# Import a site's firewall traffic rules by the site ID
+terraform import netlify_site_firewall_traffic_rules.blog 12345667-0000-0000-0000-abcdef012345
diff --git a/examples/resources/netlify_site_firewall_traffic_rules/resource.tf b/examples/resources/netlify_site_firewall_traffic_rules/resource.tf
new file mode 100644
index 0000000..d704da5
--- /dev/null
+++ b/examples/resources/netlify_site_firewall_traffic_rules/resource.tf
@@ -0,0 +1,30 @@
+resource "netlify_site_firewall_traffic_rules" "blog" {
+  site_id = data.netlify_site.blog.id
+  published = {
+    default_action = "allow"
+    ip_restrictions = [
+      {
+        description = "bot network"
+        addresses = [
+          "192.0.2.0/24",
+          "198.51.100.0/24",
+        ]
+      }
+    ]
+    geo_exceptions = [
+      {
+        description = "brazil"
+        countries   = ["BR"]
+      }
+    ]
+  }
+  unpublished = {
+    default_action = "deny"
+    ip_exceptions = [
+      {
+        description = "Allow the VPN IP"
+        addresses   = ["203.0.113.65/32"]
+      }
+    ]
+  }
+}
diff --git a/examples/resources/netlify_team_firewall_traffic_rules/import.sh b/examples/resources/netlify_team_firewall_traffic_rules/import.sh
new file mode 100644
index 0000000..bd90c5a
--- /dev/null
+++ b/examples/resources/netlify_team_firewall_traffic_rules/import.sh
@@ -0,0 +1,2 @@
+# Import a team's firewall traffic rules by the team ID
+terraform import netlify_team_firewall_traffic_rules.team 6600abcdef1234567890abcd
diff --git a/examples/resources/netlify_team_firewall_traffic_rules/resource.tf b/examples/resources/netlify_team_firewall_traffic_rules/resource.tf
new file mode 100644
index 0000000..d669706
--- /dev/null
+++ b/examples/resources/netlify_team_firewall_traffic_rules/resource.tf
@@ -0,0 +1,30 @@
+resource "netlify_team_firewall_traffic_rules" "team" {
+  site_id = data.netlify_team.team.id
+  published = {
+    default_action = "allow"
+    ip_restrictions = [
+      {
+        description = "bot network"
+        addresses = [
+          "192.0.2.0/24",
+          "198.51.100.0/24",
+        ]
+      }
+    ]
+    geo_exceptions = [
+      {
+        description = "brazil"
+        countries   = ["BR"]
+      }
+    ]
+  }
+  unpublished = {
+    default_action = "deny"
+    ip_exceptions = [
+      {
+        description = "Allow the VPN IP"
+        addresses   = ["203.0.113.65/32"]
+      }
+    ]
+  }
+}
diff --git a/go.sum b/go.sum
index 4ea736c..18af1a0 100644
--- a/go.sum
+++ b/go.sum
@@ -122,12 +122,8 @@ github.com/hashicorp/terraform-json v0.22.1 h1:xft84GZR0QzjPVWs4lRUwvTcPnegqlyS7
 github.com/hashicorp/terraform-json v0.22.1/go.mod h1:JbWSQCLFSXFFhg42T7l9iJwdGXBYV8fmmD6o/ML4p3A=
 github.com/hashicorp/terraform-plugin-docs v0.19.4 h1:G3Bgo7J22OMtegIgn8Cd/CaSeyEljqjH3G39w28JK4c=
 github.com/hashicorp/terraform-plugin-docs v0.19.4/go.mod h1:4pLASsatTmRynVzsjEhbXZ6s7xBlUw/2Kt0zfrq8HxA=
-github.com/hashicorp/terraform-plugin-framework v1.9.0 h1:caLcDoxiRucNi2hk8+j3kJwkKfvHznubyFsJMWfZqKU=
-github.com/hashicorp/terraform-plugin-framework v1.9.0/go.mod h1:qBXLDn69kM97NNVi/MQ9qgd1uWWsVftGSnygYG1tImM=
 github.com/hashicorp/terraform-plugin-framework v1.10.0 h1:xXhICE2Fns1RYZxEQebwkB2+kXouLC932Li9qelozrc=
 github.com/hashicorp/terraform-plugin-framework v1.10.0/go.mod h1:qBXLDn69kM97NNVi/MQ9qgd1uWWsVftGSnygYG1tImM=
-github.com/hashicorp/terraform-plugin-framework-validators v0.12.0 h1:HOjBuMbOEzl7snOdOoUfE2Jgeto6JOjLVQ39Ls2nksc=
-github.com/hashicorp/terraform-plugin-framework-validators v0.12.0/go.mod h1:jfHGE/gzjxYz6XoUwi/aYiiKrJDeutQNUtGQXkaHklg=
 github.com/hashicorp/terraform-plugin-framework-validators v0.13.0 h1:bxZfGo9DIUoLLtHMElsu+zwqI4IsMZQBRRy4iLzZJ8E=
 github.com/hashicorp/terraform-plugin-framework-validators v0.13.0/go.mod h1:wGeI02gEhj9nPANU62F2jCaHjXulejm/X+af4PdZaNo=
 github.com/hashicorp/terraform-plugin-go v0.23.0 h1:AALVuU1gD1kPb48aPQUjug9Ir/125t+AAurhqphJ2Co=
diff --git a/internal/provider/dns_record_resource.go b/internal/provider/dns_record_resource.go
index 99d52b5..9e5496e 100644
--- a/internal/provider/dns_record_resource.go
+++ b/internal/provider/dns_record_resource.go
@@ -71,6 +71,8 @@ func (r *dnsRecordResource) Configure(_ context.Context, req resource.ConfigureR
 
 func (r *dnsRecordResource) Schema(_ context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
+		Description:         "Netlify DNS record",
+		MarkdownDescription: "Netlify DNS record. [Read more](https://docs.netlify.com/domains-https/netlify-dns/)",
 		Attributes: map[string]schema.Attribute{
 			"zone_id": schema.StringAttribute{
 				Required: true,
@@ -88,7 +90,8 @@ func (r *dnsRecordResource) Schema(_ context.Context, _ resource.SchemaRequest,
 				Computed: true,
 			},
 			"type": schema.StringAttribute{
-				Required: true,
+				Required:    true,
+				Description: "One of A, AAAA, ALIAS, CAA, CNAME, MX, NS, SPF, or TXT",
 				Validators: []validator.String{
 					stringvalidator.OneOf(
 						"A",
@@ -106,7 +109,8 @@ func (r *dnsRecordResource) Schema(_ context.Context, _ resource.SchemaRequest,
 				},
 			},
 			"hostname": schema.StringAttribute{
-				Required: true,
+				Required:    true,
+				Description: "The hostname for the DNS record. For example, `www.example.com`.",
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplace(),
 				},
diff --git a/internal/provider/dns_zone_resource.go b/internal/provider/dns_zone_resource.go
index 3f49530..ace8605 100644
--- a/internal/provider/dns_zone_resource.go
+++ b/internal/provider/dns_zone_resource.go
@@ -64,6 +64,8 @@ func (r *dnsZoneResource) Configure(_ context.Context, req resource.ConfigureReq
 
 func (r *dnsZoneResource) Schema(_ context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
+		Description:         "Netlify DNS zone",
+		MarkdownDescription: "Netlify DNS zone. [Read more](https://docs.netlify.com/domains-https/netlify-dns/)",
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
 				Computed: true,
diff --git a/internal/provider/environment_variable_resource.go b/internal/provider/environment_variable_resource.go
index c54bc90..7c8a9b3 100644
--- a/internal/provider/environment_variable_resource.go
+++ b/internal/provider/environment_variable_resource.go
@@ -76,6 +76,8 @@ func (r *environmentVariableResource) Configure(_ context.Context, req resource.
 
 func (r *environmentVariableResource) Schema(_ context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
+		Description:         "Environment variables for Netlify sites",
+		MarkdownDescription: "Environment variables for Netlify sites. [Read more](https://docs.netlify.com/environment-variables/overview/)",
 		Attributes: map[string]schema.Attribute{
 			"last_updated": schema.StringAttribute{
 				Computed: true,
@@ -102,6 +104,7 @@ func (r *environmentVariableResource) Schema(_ context.Context, _ resource.Schem
 				Optional:    true,
 				Computed:    true,
 				ElementType: types.StringType,
+				Description: "One or more of builds, functions, runtime, and post-processing",
 				Validators: []validator.Set{
 					setvalidator.ValueStringsAre(
 						stringvalidator.OneOf("builds", "functions", "runtime", "post-processing"),
@@ -123,7 +126,8 @@ func (r *environmentVariableResource) Schema(_ context.Context, _ resource.Schem
 							Required: true,
 						},
 						"context": schema.StringAttribute{
-							Required: true,
+							Required:    true,
+							Description: "One of all, dev, branch-deploy, deploy-preview, production, or branch",
 							Validators: []validator.String{
 								stringvalidator.OneOf("all", "dev", "branch-deploy", "deploy-preview", "production", "branch"),
 							},
@@ -153,7 +157,8 @@ func (r *environmentVariableResource) Schema(_ context.Context, _ resource.Schem
 							Sensitive: true,
 						},
 						"context": schema.StringAttribute{
-							Required: true,
+							Required:    true,
+							Description: "One of all, dev, branch-deploy, deploy-preview, production, or branch",
 							Validators: []validator.String{
 								stringvalidator.OneOf("all", "dev", "branch-deploy", "deploy-preview", "production", "branch"),
 							},
diff --git a/internal/provider/firewall_traffic_rules_resource.go b/internal/provider/firewall_traffic_rules_resource.go
index b8e5099..5bb8352 100644
--- a/internal/provider/firewall_traffic_rules_resource.go
+++ b/internal/provider/firewall_traffic_rules_resource.go
@@ -129,7 +129,8 @@ func (r *firewallTrafficRulesResource) Schema(_ context.Context, _ resource.Sche
 		Required: true,
 		Attributes: map[string]schema.Attribute{
 			"default_action": schema.StringAttribute{
-				Required: true,
+				Required:    true,
+				Description: "One of allow or deny",
 				Validators: []validator.String{
 					stringvalidator.OneOf("allow", "deny"),
 					netlify_validators.ForbiddenIfEquals(
@@ -158,7 +159,21 @@ func (r *firewallTrafficRulesResource) Schema(_ context.Context, _ resource.Sche
 		},
 	}
 
+	var (
+		description   string
+		mdDescription string
+	)
+	if r.teamLevel {
+		description = "Netlify team-level firewall traffic rules"
+		mdDescription = "Netlify team-level firewall traffic rules. [Read more](https://docs.netlify.com/security/secure-access-to-sites/traffic-rules/)"
+	} else {
+		description = "Netlify site-level firewall traffic rules"
+		mdDescription = "Netlify site-level firewall traffic rules. [Read more](https://docs.netlify.com/security/secure-access-to-sites/traffic-rules/)"
+	}
+
 	resp.Schema = schema.Schema{
+		Description:         description,
+		MarkdownDescription: mdDescription,
 		Attributes: map[string]schema.Attribute{
 			"site_id": schema.StringAttribute{
 				Required: !r.teamLevel,
diff --git a/internal/provider/log_drain_resource.go b/internal/provider/log_drain_resource.go
index 5da0b8e..78b6fd1 100644
--- a/internal/provider/log_drain_resource.go
+++ b/internal/provider/log_drain_resource.go
@@ -81,6 +81,8 @@ func (r *logDrainResource) Configure(_ context.Context, req resource.ConfigureRe
 
 func (r *logDrainResource) Schema(_ context.Context, _ resource.SchemaRequest, resp *resource.SchemaResponse) {
 	resp.Schema = schema.Schema{
+		Description:         "Netlify log drain",
+		MarkdownDescription: "Netlify log drain. [Read more](https://docs.netlify.com/monitor-sites/log-drains/)",
 		Attributes: map[string]schema.Attribute{
 			"id": schema.StringAttribute{
 				Computed: true,
@@ -102,6 +104,7 @@ func (r *logDrainResource) Schema(_ context.Context, _ resource.SchemaRequest, r
 				PlanModifiers: []planmodifier.String{
 					stringplanmodifier.RequiresReplace(),
 				},
+				Description: "One of datadog, newrelic, logflare, s3, splunkcloud, http, axiom, or azure",
 				Validators: []validator.String{
 					stringvalidator.OneOf(
 						"datadog",
@@ -136,13 +139,15 @@ func (r *logDrainResource) Schema(_ context.Context, _ resource.SchemaRequest, r
 				},
 			},
 			"format": schema.StringAttribute{
-				Optional: true,
-				Computed: true,
-				Default:  stringdefault.StaticString("json"),
+				Optional:    true,
+				Computed:    true,
+				Description: "json or ndjson",
+				Default:     stringdefault.StaticString("json"),
 			},
 			"log_types": schema.SetAttribute{
 				Required:    true,
 				ElementType: types.StringType,
+				Description: "One or more of user_traffic, functions, edge_functions, and deploys",
 				Validators: []validator.Set{
 					setvalidator.ValueStringsAre(
 						stringvalidator.OneOf("user_traffic", "functions", "edge_functions", "deploys"),
diff --git a/internal/provider/provider.go b/internal/provider/provider.go
index 5cabbd1..d87f8d3 100644
--- a/internal/provider/provider.go
+++ b/internal/provider/provider.go
@@ -42,7 +42,7 @@ func (p *NetlifyProvider) Schema(ctx context.Context, req provider.SchemaRequest
 				Optional:            true,
 			},
 			"token": schema.StringAttribute{
-				MarkdownDescription: "Read: https://docs.netlify.com/api/get-started/",
+				MarkdownDescription: "Read: https://docs.netlify.com/api/get-started/#authentication , will use the `NETLIFY_API_TOKEN` environment variable if not set.",
 				Optional:            true,
 				Sensitive:           true,
 			},
diff --git a/templates/index.md.tmpl b/templates/index.md.tmpl
index 54351d1..2b7c8ac 100644
--- a/templates/index.md.tmpl
+++ b/templates/index.md.tmpl
@@ -7,6 +7,32 @@ description: |-
 
 # Netlify Provider
 
-The Netlify provider provides resources to interact with a Netlify account.
+The Netlify provider provides resources to manage Netlify resources like site configuration, environment variables, and Advanced Web Security features.
+
+## Authentication
+
+To use the provider, you will need a [personal access token](https://docs.netlify.com/api/get-started/#authentication).
+You can create a new token in the [Netlify app](https://app.netlify.com/user/applications#personal-access-tokens).
+
+You can expose the token as an environment variable:
+```bash
+export NETLIFY_API_TOKEN="your-personal-access-token"
+```
+
+Or by creating a Terraform variable:
+```terraform
+variable "netlify_api_token" {
+  type = string
+}
+
+provider "netlify" {
+  token = var.netlify_api_token
+}
+```
+and setting the variable's value as an environment variable (`TF_VAR_netlify_api_token`).
+
+## Example Usage
+
+{{tffile "examples/provider/provider.tf"}}
 
 {{ .SchemaMarkdown | trimspace }}