(chore) steps component now accepts h2s (#1801)

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.
 

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/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:
 

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

@@ -20,10 +20,8 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO.
   - Use Google Workspace to enable single sign-on (SSO) via SAML for your Clerk application.
 </TutorialHero>
 
-## Tutorial
-
 <Steps>
-  ### Set up an enterprise connection in Clerk
+  ## Set up an enterprise connection in Clerk
 
   To create a SAML connection in Clerk:
 
@@ -34,7 +32,7 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO.
   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'll be redirected to the connection's configuration page.
 
-  ### Create a new enterprise application in Google
+  ## Create a new enterprise application in Google
 
   To create a new enterprise application in Google:
 
@@ -45,20 +43,20 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO.
   1. In the **App details** section, an **App name** is required.
   1. Select the **Continue** button.
 
-  ### 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 input the URL to your IdP's metadata file. This is the recommended way to configure your IdP.
   - [**Custom configuration**](#custom-configuration) - This is where you can manually input the configuration settings for your IdP.
 
-  #### Metadata configuration
+  ### Metadata configuration
 
   1. In the Google Admin Console, under **Option 1: Download IdP Metadata**, select the **Download Metadata** button.
   1. Navigate back to the Clerk Dashboard and in the **Identity Provider Configuration** section, select the **Upload file** button.
   1. Upload the metadata file you downloaded from Google.
 
-  #### Custom configuration
+  ### Custom configuration
 
   If you choose to manually input the configuration settings for your IdP, you must add these three fields to your Clerk settings:
 
@@ -71,7 +69,7 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO.
   1. Fill in the **SSO URL**, **Entity ID**, and upload the **Certificate**. Don't forget to select **Save**.
   1. In the Google Admin Console, select the **Continue** button.
 
-  ### Configure your service provider
+  ## Configure your service provider
 
   To configure your service provider (Clerk), you will need to add these two fields to your IdP's application:
 
@@ -85,7 +83,7 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO.
   1. In the Google Admin Console, paste these values into their respective fields.
   1. Under the **Name ID** section, select the dropdown for **Name ID format** and select **Email**.
 
-  ### Map Google claims to Clerk attributes
+  ## Map Google 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.
 
@@ -103,7 +101,7 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO.
   1. Enter `mail` in the field.
   1. If you have additional claims that you would like to map to Clerk, you can do so by following the steps in the [Map other claims](#map-other-claims-optional) section. Otherwise, select the **Finish** button.
 
-  #### Map other claims (optional)
+  ### Map other claims (optional)
 
   In Clerk, the [`User`](/docs/users/overview#user-object) object has a `publicMetadata` property that you can use to store additional information about your users.
 
@@ -121,15 +119,15 @@ description: Learn how to integrate Google Workspace with Clerk using SAML SSO.
 
   Learn more about [how to access the metadata from our APIs](/docs/users/metadata).
 
-  ### Enable the connection on Google
+  ## Enable the connection on Google
 
   Once the configuration is complete, you will be redirected to the app details page.
 
   1. In the **User access** section, select **View details**.
   1. In the **Service status** section, select **ON for everyone**.
   1. Select the **Save** button.
 
-  ### 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/okta.mdx

@@ -20,10 +20,8 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO.
   - Use Okta Workforce to enable single sign-on (SSO) via SAML for your Clerk application.
 </TutorialHero>
 
-## Tutorial
-
 <Steps>
-  ### Set up an enterprise connection in Clerk
+  ## Set up an enterprise connection in Clerk
 
   To create a SAML connection in Clerk:
 
@@ -37,7 +35,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO.
   1. Save the **Single sign-on URL** and the **Audience URI (SP Entity ID)** values somewhere secure. You'll need these in the [Configure your service provider](#configure-your-service-provider) step.
   1. Leave this page open.
 
-  ### Create a new enterprise application in Okta
+  ## Create a new enterprise application in Okta
 
   To create a new enterprise application in Okta:
 
@@ -49,7 +47,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO.
   1. Once redirected to the **Create SAML Integration** page, fill in the **General Settings** fields. An **App name** is required.
   1. Select the **Next** button to continue.
 
-  ### Configure your service provider
+  ## Configure your service provider
 
   Once you have moved forward from the **General Settings** instructions, you will be presented with the **Configure SAML** page.
 
@@ -62,7 +60,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO.
 
   1. Paste the **Single sign-on URL** and the **Audience URI (SP Entity ID)** values that you saved earlier into their respective fields.
 
-  ### Map Okta claims to Clerk attributes
+  ## Map Okta 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.
 
@@ -84,7 +82,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO.
   1. Scroll to the bottom of the page and select the **Next** button to continue.
   1. You will be redirected to the **Feedback** page. Fill out the feedback however you would like and select the **Finish** button to complete the setup.
 
-  ### Assign selected user or group in Okta
+  ## Assign selected user or group in Okta
 
   You need to assign your users/user groups to your enterprise application. For example, if you were part of the Clerk organization, you would have access to users and groups in the Clerk organization. In this case, you could assign one or more users or entire groups to the enterprise application you just created.
 
@@ -94,7 +92,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO.
   1. Select the **Assign** button next to the user or group that you want to assign.
   1. Select the **Done** button to complete the assignment.
 
-  ### Configure your identity provider
+  ## Configure your identity provider
 
   Once you have completed the setup in Okta, you will be redirected to the application instances page with the **Sign On** tab selected.
 
@@ -103,7 +101,7 @@ description: Learn how to integrate Okta Workforce with Clerk using SAML SSO.
   1. Under the **Metadata configuration** option, paste the **Metadata URL**.
   1. Select the **Fetch & save** button to complete the setup.
 
-  ### Enable the connection for Clerk
+  ## Enable the connection for Clerk
 
   To make the connection available for your users to authenticate with: