Merge branch 'main' into rob/eco-224-vue-sdk-references

CONTRIBUTING.md

@@ -439,18 +439,18 @@ console.log('ignored')
 
 ### `<Steps />`
 
-The `<Steps />` component is used to number a set of instructions with an outcome. It uses the highest heading available in the component to denote each step. Can be used with `h3` headings.
+The `<Steps />` component is used to number a set of instructions with an outcome. It uses the highest heading available in the component to denote each step. Can be used with `h2` and `h3` headings.
 
 ```mdx
 <Steps>
 
-### Step 1
+## Step 1
 
 Do these actions to complete Step 1.
 
-### Another step
+## Another step
 
-#### A heading inside a step
+### A heading inside a step
 
 Do these actions to complete Step 2.
 
@@ -468,7 +468,7 @@ A callout draws attention to something learners should slow down and read.
 > [!NOTE]
 > Callouts can be distracting when people are quickly skimming a page. So only use them if the information absolutely should not be missed!
 
-Callout syntax is based on [GitHub's markdown "alerts"](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts). To add a callout, use a special blockquote line specifying the callout type, followed by the callout information in a standard blockquote. Five types of callouts are available:
+Callout syntax is based on [GitHub's markdown "alerts"](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts). To add a callout, use a special blockquote line specifying the callout type, followed by the callout information in a standard blockquote. The following types of callouts are available:
 
 ```mdx
 > [!NOTE]
@@ -485,11 +485,34 @@ Callout syntax is based on [GitHub's markdown "alerts"](https://docs.github.com/
 
 > [!CAUTION]
 > Advises about risks or negative outcomes of certain actions.
+
+> [!QUIZ]
+> An opportunity for users to check their understanding.
 ```
 
 The image below shows what this example looks like once rendered.
 
-![An example of each callout type: NOTE, TIP, IMPORTANT, WARNING, CAUTION](/.github/media/callouts.png)
+![An example of each callout type: NOTE, TIP, IMPORTANT, WARNING, CAUTION, QUIZ](/.github/media/callouts.png)
+
+You can optionally specify an `id` attribute for a callout which allows for direct linking, e.g. `/docs/example#useful-info`:
+
+```mdx
+> [!NOTE useful-info]
+> Useful information that users should know, even when skimming content.
+```
+
+You can create a collapsible section within a callout by using a thematic break (`---`). Content following the break is hidden by default and can be toggled by the user:
+
+```mdx
+> [!QUIZ]
+> Why does handshake do a redirect? Why can’t it make a fetch request to FAPI and get a new token back that way? Not needing to redirect would be a better user experience.
+>
+> ---
+>
+> Occaecati esse ut iure in quam praesentium nesciunt nemo. Repellat aperiam eaque quia. Aperiam voluptatem consequuntur numquam tenetur. Quibusdam repellat modi qui dolor ducimus ut neque adipisci dolorem. Voluptates dolores nisi est fuga.
+```
+
+![An example of a collapsible section inside a quiz callout](/.github/media/callout-details.png)
 
 ### `<CodeBlockTabs />`
 

docs/authentication/enterprise-connections/oidc/custom-provider.mdx

@@ -25,7 +25,7 @@ This guide explains how to use a custom [OpenID Connect (OIDC)](https://openid.n
 To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your Identity Provider (IdP).
 
 <Steps>
-  ### Set up an enterprise connection in Clerk
+  ## Set up an enterprise connection in Clerk
 
   1. In the Clerk Dashboard, navigate to the [**SSO Connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page.
   1. Select **Add connection** and select **For specific domains**.
@@ -35,14 +35,14 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your app.
   1. Select **Add connection**. You will be redirected to the connection's configuration page. Keep this page open.
 
-  ### Configure your IdP
+  ## Configure your IdP
 
   1. If necessary, create a new application in your IdP.
   1. In the connection's configuration page of the Clerk Dashboard, copy the **Authorized redirect URI**.
   1. Add the value to your IdP's whitelisted URLs.
   1. Find your application's **Discovery Endpoint**, **Client ID**, and **Client Secret** and copy them.
 
-  ### Set the Discovery Endpoint, Client ID, and Client Secret in Clerk
+  ## Set the Discovery Endpoint, Client ID, and Client Secret in Clerk
 
   1. In your IdP settings, copy your application's **Discovery Endpoint**, **Client ID**, and **Client Secret**.
   1. In the connection's configuration page in the Clerk Dashboard, paste these values in their respective fields.
@@ -52,7 +52,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   > [!NOTE]
   > Most IdPs provide a **Discovery Endpoint** to retrieve metadata about an OIDC provider. If your IdP doesn't offer this endpoint or if you need greater control over the setup process, in the connection's configuration page in the Clerk Dashboard, find the **Identity Provider Configuration** section and select **Use Manual Configuration** to manually configure the connection.
 
-  ### Configure attribute mapping (optional)
+  ## Configure attribute mapping (optional)
 
   Clerk expects the claims returned by your IdP to follow the [OIDC Standard](https://openid.net/specs/openid-connect-core-1_0.html#StandardClaims). If your provider returns claims in a non-standard format, use the **Attribute Mapping** section on the connection's configuration page to adjust the mapping of Clerk's user properties to match the IdP's claim attributes.
 
@@ -61,22 +61,22 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   >
   > If the IdP doesn't return this claim, you can leave the **Email address verified** field blank and set the **Default value** to **True**. This should only be done if you fully trust the IdP, as it can expose your app to [OAuth attacks](https://www.descope.com/blog/post/noauth).
 
-  ### Allow additional identifiers (optional)
+  ## Allow additional identifiers (optional)
 
   User profile information is sourced from the IdP. To allow users to add new identifiers (e.g., email address or phone number) to their profiles:
 
   1. In the connection's configuration page of the Clerk Dashboard, navigate to the **Advanced** tab.
   1. Enable **Allow additional identifiers**.
   1. Select **Save**.
 
-  ### Enable the connection for Clerk
+  ## Enable the connection for Clerk
 
   To make the connection available for your users to authenticate with:
 
   1. Navigate back to the Clerk Dashboard where you should still have the connection's configuration page open. If not, navigate to the [**SSO connections**](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) page and select the connection.
   1. At the top of the page, toggle on **Enable connection** and select **Save**.
 
-  ### Test your connection
+  ## Test your connection
 
   The simplest way to test your enterprise connection is to visit your Clerk app's [Account Portal](/docs/customization/account-portal/overview), which is available for all Clerk apps out-of-the-box.
 

docs/authentication/enterprise-connections/overview.mdx

@@ -47,7 +47,7 @@ It is ultimately the app's responsibility to handle this unauthenticated state a
 
 ### SAML vs. EASIE
 
-The primary security difference between EASIE SSO and SAML SSO is that EASIE depends on a multi-tenant identity provider, while SAML depends on a single-tenant identity provider. Relying on a multi-tenant provider **increases** the risk that a user from one tenant will mistakenly be granted access to the resources of another tenant. While Clerk implements [measures to address this risk](https://easie.dev/#mitigating-tenant-crossover-vulnerabilities), apps that require single-tenant IdPs should opt for SAML.
+The primary security difference between EASIE SSO and SAML SSO is that EASIE depends on a multi-tenant identity provider, while SAML depends on a single-tenant identity provider. Relying on a multi-tenant provider **increases** the risk that a user from one tenant will mistakenly be granted access to the resources of another tenant. While Clerk implements [measures to address this risk](https://easie.dev/#mitigating-tenant-crossover-vulnerabilities:~:text=4.%20Mitigating%20tenant%20crossover%20vulnerabilities), apps that require single-tenant IdPs should opt for SAML.
 
 For more information, see the [EASIE docs](https://easie.dev#security).
 
@@ -78,7 +78,3 @@ Yes, for SAML only. Clerk supports both Service Provider-initiated (SP-initiated
 For development instances, Enterprise connections are always free but limited to a maximum of 25.
 
 Production instances require the Pro plan and the Enhanced Authentication Add-on. Please see [pricing](/pricing){{ target: '_blank' }} for more information.
-
-### Can I get a bulk discount?
-
-Yes, [contact support](/contact/support){{ target: '_blank' }} to work out a custom plan.

docs/authentication/enterprise-connections/saml/azure.mdx

@@ -25,7 +25,7 @@ Enabling single sign-on (SSO) with **Microsoft Azure Entra ID** (formerly [Activ
 To make the setup process easier, it's recommended to keep two browser tabs open: one for the [Clerk Dashboard](https://dashboard.clerk.com/last-active?path=user-authentication/sso-connections) and one for your [Microsoft Azure portal](https://portal.azure.com).
 
 <Steps>
-  ### Set up an enterprise connection in Clerk
+  ## Set up an enterprise connection in Clerk
 
   To create a SAML connection in Clerk:
 
@@ -38,7 +38,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   1. Find the **Service Provider Configuration** section.
   1. Save the **Identifier (Entity ID)** and **Reply URL (Assertion Consumer Service URL)** values somewhere secure. You'll need these in the [Configure your service provider](#configure-your-service-provider) step. Leave this page open.
 
-  ### Create a new enterprise app in Microsoft
+  ## Create a new enterprise app in Microsoft
 
   To create a new enterprise app in Microsoft:
 
@@ -52,7 +52,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   - Ensure the option **Integrate any other application you don't find in the gallery (Non-gallery)** is selected.
   - Select **Create**.
 
-  ### Assign selected user or group in Microsoft
+  ## Assign selected user or group in Microsoft
 
   Now that you have created the enterprise app, you need to assign users or groups to the app. For example, if you were part of the Clerk organization, you would have access to users and groups within the Clerk organization. In this case, you could assign individual users or entire groups to the enterprise app you just created.
 
@@ -63,14 +63,14 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   1. Select **Select** at the bottom of the page. You'll be redirected to the **Add Assignment** page.
   1. Select **Assign** at the bottom of the page.
 
-  ### Configure SSO in Microsoft
+  ## Configure SSO in Microsoft
 
   After assigning the user or group to the enterprise app, you need to configure the SSO settings to enable SAML SSO.
 
   1. In the navigation sidebar, open the **Manage** dropdown and select **Single sign-on**.
   1. In the **Select a single sign-on method** section, select **SAML**.
 
-  ### Configure your service provider
+  ## Configure your service provider
 
   To configure Clerk as your service provider, add these two fields to your IdP's application:
 
@@ -84,7 +84,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   1. Paste the **Identifier (Entity ID)** and **Reply URL (Assertion Consumer Service URL)** values you saved earlier into their respective fields. These values will be saved automatically.
   1. Select **Save** at the top of the panel. Close the panel.
 
-  ### Configure your identity provider
+  ## Configure your identity provider
 
   To configure Microsoft Entra ID as your identity provider, add the following fields to your app:
 
@@ -93,7 +93,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   1. Navigate back to the **Clerk Dashboard**. In the **Identity Provider Configuration** section, under **App Federation Metadata Url**, paste the **App Federation Metadata URL**.
   1. Select **Fetch & save**.
 
-  ### Map Microsoft claims to Clerk attributes
+  ## Map Microsoft claims to Clerk attributes
 
   Mapping the claims in your IdP to the attributes in Clerk ensures that the data from your IdP is correctly mapped to the data in Clerk.
 
@@ -112,7 +112,7 @@ To make the setup process easier, it's recommended to keep two browser tabs open
   1. Next to **Source attribute**, search for and select `user.userprincipalname` in the dropdown.
   1. Select **Save** at the top of the page.
 
-  ### Enable the connection for Clerk
+  ## Enable the connection for Clerk
 
   To make the connection available for your users to authenticate with:
 

docs/authentication/enterprise-connections/saml/custom-provider.mdx

@@ -22,10 +22,8 @@ description: Learn how to integrate an Identity Provider with Clerk using SAML S
 
 Clerk supports Enterprise SSO via the SAML protocol, enabling you to create authentication strategies for an Identity Provider (IdP). Currently, Clerk offers direct integrations with [Microsoft Azure AD](/docs/authentication/enterprise-connections/saml/azure), [Google Workspace](/docs/authentication/enterprise-connections/saml/google), and [Okta Workforce](/docs/authentication/enterprise-connections/saml/okta) as IdPs. However, you can also integrate with any other IdP that supports the SAML protocol. This guide will show you how to set up a SAML connection with a custom IdP in Clerk.
 
-## Tutorial
-
 <Steps>
-  ### Set up an enterprise connection in Clerk
+  ## Set up an enterprise connection in Clerk
 
   To create a SAML connection in Clerk:
 
@@ -36,23 +34,23 @@ Clerk supports Enterprise SSO via the SAML protocol, enabling you to create auth
   1. Add the **Specific Domain** that you want to allow this connection for. This is the domain of the users you want to allow to sign in to your application.
   1. Select **Add connection**. You will be redirected to the connection's configuration page.
 
-  ### Create a new enterprise application in your IdP
+  ## Create a new enterprise application in your IdP
 
   Create a new application in your IdP. In the next steps, you'll configure your IdP with the settings provided by your Service Provider (Clerk), and configure Clerk with the settings provided by your IdP. Keep both the IdP and Clerk Dashboard open.
 
-  ### Configure your Identity Provider
+  ## Configure your Identity Provider
 
   There are two options for configuring your IdP:
 
   - [**Metadata configuration**](#metadata-configuration) - This is where you can download your IdP's metadata file or input the metadata URL that you got from your IdP. This is the recommended way to configure your IdP, but not all IdPs support this method.
   - [**Custom configuration**](#custom-configuration) - This is where you can manually input the configuration settings for your IdP.
 
-  #### Metadata configuration
+  ### Metadata configuration
 
   1. In your IdP dashboard, find where you can download the metadata file or copy the metadata URL.
   1. In the Clerk Dashboard on the connection's configuration page, under **Identity Provider Configuration**,select **Add via metadata**. Input the metadata URL or upload the metadata file that you got from your IdP.
 
-  #### Custom configuration
+  ### Custom configuration
 
   If you choose to manually input the configuration settings for your IdP, you will need to fill these three fields in the Clerk Dashboard: