[Turnstile] Documentation overhaul

public/__redirects

@@ -1536,6 +1536,16 @@
 /turnstile/concepts/widget-types/ /turnstile/concepts/widget/ 301
 /turnstile/concepts/domain-management/ /turnstile/concepts/hostname-management/ 301
 /turnstile/troubleshooting/challenge-solve-issues/ /cloudflare-challenges/troubleshooting/challenge-solve-issues/ 301
+/turnstile/concepts/ephemeral-id/ /turnstile/additional-configuration/ephemeral-id/ 301
+/turnstile/concepts/hostname-management/ /turnstile/additional-configuration/hostname-management/ 301
+/turnstile/concepts/pre-clearance-support/ /cloudflare-challenges/concepts/clearance/ 301
+/turnstile/api-reference/ /turnstile/get-started/widget-management/api/ 301
+/turnstile/concepts/appearance-modes/ /turnstile/get-started/client-side-rendering/widget-configurations/ 301
+/turnstile/demos/ /turnstile/tutorials/ 301
+/turnstile/get-started/pre-clearance/ /cloudflare-challenges/concepts/clearance/ 301
+/turnstile/get-started/terraform/ /turnstile/get-started/widget-management/terraform/ 301
+/turnstile/glossary/ /turnstile/ 301
+/turnstile/get-started/supported-browsers/ /cloudflare-challenges/reference/supported-browsers/ 301
 
 # waf
 /waf/about/ /waf/concepts/ 301

src/content/docs/cloudflare-challenges/concepts/clearance.mdx

@@ -68,4 +68,27 @@ Clearance cookies generated by the Turnstile widget will be valid for the time s
 
 ### Setup
 
-To set up pre-clearance cookies for Turnstile, refer to [Enable pre-clearance cookies](/turnstile/get-started/pre-clearance/).
+To enable pre-clearance, you must ensure that the hostname of the Turnstile widget matches the zone with the WAF rules. During the Turnstile configuration setup in the Cloudflare dashboard, you can see the registered zones. Select the appropriate hostname from this list.
+
+The prerequisite is crucial for pre-clearance to function properly. If set up correctly, visitors who successfully solve Turnstile will receive a cookie with the security clearance level set by the customer. When encountering a WAF challenge on the same zone, they will bypass additional challenges for the configured clearance level and below.
+
+For more details on managing hostnames, refer to the [Hostname Management documentation](/turnstile/additional-configuration/hostname-management/).
+
+<Render file="cf-clearance-cookie" product="cloudflare-challenges" />
+
+#### Enable pre-clearance on a new site
+
+1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
+2. Go to **Turnstile** > **Add widget**.
+3. Under **Would you like to opt for pre-clearance for this site?** select **Yes**.
+4. Choose the pre-clearance level from the select box.
+5. Select **Create**.
+
+#### Enable pre-clearance on an existing site
+
+1. Log in to the [Cloudflare dashboard](https://dash.cloudflare.com/login) and select your account.
+2. Go to **Turnstile**.
+3. Go to the existing widget or site and select **Settings**.
+4. Under **Would you like to opt for pre-clearance for this site?** select **Yes**.
+5. Choose the pre-clearance level from the select box.
+6. Select **Update**.

src/content/docs/cloudflare-challenges/frequently-asked-questions.mdx

@@ -85,7 +85,7 @@ Block Amazon Web Services (AWS) and Google Cloud Platform (GCP) because of large
 
 Previously, unless you customize your front-end application, any AJAX request that is challenged will fail because AJAX calls are not rendered in the DOM.
 
-Now, you can [opt-in to Turnstile's Pre-clearance cookies](/turnstile/concepts/pre-clearance-support/). This allows you to issue a Challenge early in your web application flow and pre-clear users to interact with sensitive APIs. Clearance cookies issued by a Turnstile widget are automatically applied to the Cloudflare zone that the Turnstile widget is embedded on, with no configuration necessary. The duration of the clearance cookie's validity is controlled by the zone-specific configurable [Challenge Passage](/cloudflare-challenges/challenge-types/challenge-pages/challenge-passage/) security setting.
+Now, you can [opt-in to Turnstile's Pre-clearance cookies](/cloudflare-challenges/concepts/clearance/#pre-clearance-support-in-turnstile). This allows you to issue a Challenge early in your web application flow and pre-clear users to interact with sensitive APIs. Clearance cookies issued by a Turnstile widget are automatically applied to the Cloudflare zone that the Turnstile widget is embedded on, with no configuration necessary. The duration of the clearance cookie's validity is controlled by the zone-specific configurable [Challenge Passage](/cloudflare-challenges/challenge-types/challenge-pages/challenge-passage/) security setting.
 
 ## Why would I not find any failed Challenges?
 

src/content/docs/turnstile/additional-configuration/index.mdx

@@ -0,0 +1,15 @@
+---
+title: Additional configurations
+pcx_content_type: navigation
+sidebar:
+  order: 5
+  group:
+    hideIndex: true
+
+---
+
+import { DirectoryListing } from "~/components"
+
+Refer to the following pages for more information about Turnstile's additional configurations:
+
+<DirectoryListing />

src/content/docs/turnstile/concepts/challenges.mdx

@@ -0,0 +1,8 @@
+---
+title: Cloudflare Challenges
+pcx_content_type: navigation
+external_link: /cloudflare-challenges/
+sidebar:
+  order: 2
+
+---

src/content/docs/turnstile/concepts/index.mdx

@@ -10,6 +10,6 @@ sidebar:
 
 import { DirectoryListing } from "~/components"
 
-Refer to the following pages for more information about Turnstile concepts:
+Refer to the following pages for more information about Turnstile's concepts:
 
-<DirectoryListing />
+<DirectoryListing />

src/content/docs/turnstile/concepts/widget.mdx

@@ -1,107 +1,85 @@
 ---
-title: Widget
-pcx_content_type: reference
+title: Turnstile widgets
+pcx_content_type: concept
 sidebar:
   order: 1
-
+head:
+  - tag: title
+    content: Overview
 ---
 
 import { GlossaryTooltip, Render } from "~/components"
 
 Every instance of Turnstile belongs to a Turnstile widget. It is configured on a per-widget level. Every widget has a mode, a label, a <GlossaryTooltip term="sitekey">sitekey</GlossaryTooltip>, and a <GlossaryTooltip term="secret key">secret key</GlossaryTooltip>.
 
-The 3 modes for Turnstile are **Managed**, **Non-Interactive**, and **Invisible**.
-
-Refer to [appearance modes](/turnstile/get-started/client-side-rendering/#appearance-modes) to configure whether to have the widget be always visible or visible only when interaction is required, and to customize your widget theme between automatic, light, or dark mode.
-
-Widgets can be implemented in normal, flexible, or compact sizes.
-
-<Render file="widget-size" />
-
-Refer to [widget sizes](/turnstile/get-started/client-side-rendering/#widget-size) for an example on how to configure flexible or compact mode.
-
-:::note[Offlabel]
-Customers with Enterprise Bot Management and Enterprise Turnstile have the ability to remove the Cloudflare branding and customize a specific Turnstile widget via the [API](/api/resources/turnstile/subresources/widgets/methods/update/).
-:::
+## Widget components
 
-## Availability
+<Render file="widget-components" />
 
-Free users are limited to 20 widgets per account.
+## Widget modes
 
-Customers with Enterprise Bot Management and Enterprise Turnstile can have this limit increased. Contact your account team to increase your widget limit.
+The available modes for Turnstile widgets are **Managed**, **Non-Interactive**, and **Invisible**.
 
-## Widget types
+### Managed mode (recommended)
 
-### Managed (recommended)
+Managed mode is fully managed by Cloudflare. It automatically chooses the appropriate action based on client-side signals and risk levels. Cloudflare uses the information from the visitor to decide if an interactive challenge should be used.
 
-This mode is fully managed by Cloudflare. It automatically chooses the appropriate action based on various signals and risk levels. Cloudflare will use the information from the visitor to decide if an interactive challenge should be used. Turnstile will only require interaction if a further check is necessary to verify that the visitor is human. When an interaction is required, the user will be prompted to check a box (no images or text to decipher). This managed mode is ideal for users who want a simple configuration without needing to fine-tune the behavior.
+Turnstile will only require interaction if a further check is necessary to verify that the visitor is human. When an interaction is required, the visitor will be prompted to select a box. There will be no images or text to decipher.
 
-#### Light mode
+Managed mode is ideal for users who want a simple configuration without needing to fine-tune the widget's behavior.
 
-![Managed challenge](~/assets/images/turnstile/light-regular.png)
-![Verifying the challenge](~/assets/images/turnstile/light-verifying.png)
-![Successful managed challenge](~/assets/images/turnstile/light-success.png)
+### Non-Interactive mode
 
-#### Dark mode
+Visitors will see a widget with a loading spinner while the challenges run in their browsers. Unlike managed mode, visitors will never be required or prompted to interact with the widget.
 
-![Managed challenge](~/assets/images/turnstile/dark-regular.png)
-![Verifying the challenge](~/assets/images/turnstile/dark-verifying.png)
-![Successful managed challenge](~/assets/images/turnstile/dark-success.png)
+Non-Interactive mode is ideal for users who want to prioritize visitor experience and do not want to add any friction on their website with a Turnstile interaction.
 
-### Compact mode
+### Invisible mode
 
-You can configure the Turnstile widget in compact mode, which functions in the same way as a Managed widget.
+Invisible mode is similar to Non-Interactive mode where visitors will never interact with the Turnstile widget. Visitors will also not see a widget or any indication that an invisible browser challenge is in progress.
 
-#### Light mode
+Invisible mode is ideal for users who want to prioritize visitor and visual experience on their website.
 
-![Compact managed challenge](~/assets/images/turnstile/light-compact.png)
-
-#### Dark mode
-
-![Compact managed challenge](~/assets/images/turnstile/dark-compact.png)
-
-### Non-Interactive
-
-Visitors will see a widget with a loading bar while the browser challenges run. Unlike managed mode, visitors will never be required or prompted to interact with the widget. This mode is ideal for users who want to prioritize visitor experience and do not want to add any friction with a Turnstile interaction.
+---
 
-#### Light mode
+## Widget customization
 
-![Verifying the challenge](~/assets/images/turnstile/light-verifying.png)
-![Successful managed challenge](~/assets/images/turnstile/light-success.png)
+### Sizes
 
-#### Dark mode
+Widgets can be implemented in normal, flexible, or compact sizes.
 
-![Verifying the challenge](~/assets/images/turnstile/dark-verifying.png)
-![Successful managed challenge](~/assets/images/turnstile/dark-success.png)
+Refer to [Widget configurations](/turnstile/get-started/client-side-rendering/widget-configurations/) for detailed configuration options and code examples.
 
-### Invisible
+### Appearance and themes
 
-This mode is similar to non-interactive mode where visitors will never interact with the Turnstile widget. Visitors will not see a widget or any indication that an invisible browser challenge is in progress. Invisible challenges should take a few seconds to complete.
+Turnstile widgets support multiple appearance modes and themes to match your website's design. Refer to [Widget configurations](/turnstile/get-started/client-side-rendering/widget-configurations/) for implementation details.
 
-## Error states
+---
 
-### Unknown error state
+## Widget states
 
-![Unknown error state](~/assets/images/turnstile/unknown-error-state.png)
+### Normal operation states
 
-When an unknown error occurs during the challenge, visitors will encounter this widget state. Visitors can refresh and retry the challenge. If the error persists, they can submit a feedback form by selecting **Send feedback** on the widget.
+- **Loading**: Widget is processing the challenge.
+- **Interaction**: Visitor needs to check the box (Managed mode only).
+- **Success**: The Challenge was completed successfully.
 
-Refer to [Feedback reports](/turnstile/troubleshooting/feedback-reports) for more information.
+### Error states
 
-### Interaction timed out state
+#### Unknown error
 
-![Interaction timed out](~/assets/images/turnstile/interaction-timed-out.png)
+When an unknown error occurs during the challenge, visitors will encounter this widget state. Visitors can follow the troubleshooting guidelines from the widget or refresh the page to retry the challenge.
 
-When the challenge is not solved for an extended period of time, it must be issued again by reloading the page or the widget.
+#### Interaction timed out
 
-### Challenge timed out state
+When the visitor is presented with a checkbox but does not interact with it for an extended period of time. The challenge must be reissued by reloading the page or the widget.
 
-![Challenge timed out](~/assets/images/turnstile/challenge-timed-out.png)
+#### Challenge timed out
 
-The widget expires when a token was issued but the user did not solve the challenge after an extended period of time. The page or widget must be reloaded.
+When the verification was completed but no further action has been taken, the challenge outcome will no longer be valid. For example, if a Turnstile widget is on a login page and the Turnstile successfully ran, but the visitor did not log in for an extended period of time, the challenge must be reissued by reloading the page or the widget.
 
-### Outdated or unsupported browser
+#### Outdated or unsupported browser
 
-![Unsupported browser](~/assets/images/turnstile/unsupported-browser.png)
+Visitors with outdated browsers or unsupported browsers will encounter this widget state. 
 
-Visitors with outdated browsers or unsupported browsers will encounter this widget state. Refer to [Supported browsers](/cloudflare-challenges/#browser-support) for more information regarding supported browsers.
+Refer to [Supported browsers](/cloudflare-challenges/#browser-support) for more information regarding supported browsers.

src/content/docs/turnstile/extensions/index.mdx

@@ -2,7 +2,7 @@
 title: Extensions
 pcx_content_type: navigation
 sidebar:
-  order: 7
+  order: 9
   group:
     hideIndex: true