chore: Refactor onboarding options for unique titles (#14231)

Fixes #14221.

---------

Co-authored-by: Cursor Agent <[email protected]>
Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>
Co-authored-by: seer-by-sentry[bot] <157164994+seer-by-sentry[bot]@users.noreply.github.com>

Author: 4 people

app/globals.css

@@ -165,3 +165,18 @@ body {
 {
   color: rgb(134, 142, 150) !important;
 }
+
+/* CSS Counters for Onboarding Steps */
+.onboarding-steps {
+  counter-reset: onboarding-step;
+}
+
+.onboarding-step {
+  counter-increment: onboarding-step;
+}
+
+.onboarding-step .step-heading::before,
+.onboarding-step h2::before {
+  content: "Step " counter(onboarding-step) ": ";
+  font-weight: inherit;
+}

docs/platforms/javascript/guides/react/index.mdx

@@ -11,7 +11,11 @@ categories:
 
 <PlatformContent includePath="getting-started-prerequisites" />
 
-## Step 1: Install
+<OnboardingSteps>
+
+<OnboardingOption isStep>
+
+## Install
 
 Choose the features you want to configure, and this guide will show you how:
 
@@ -37,7 +41,11 @@ yarn add @sentry/react
 pnpm add @sentry/react
 ```
 
-## Step 2: Configure
+</OnboardingOption>
+
+<OnboardingOption isStep>
+
+## Configure
 
 ### Initialize the Sentry SDK
 
@@ -112,8 +120,9 @@ const container = document.getElementById(“app”);
 const root = createRoot(container);
 root.render(<App />);
 ```
-
-## Step 3: Capture React Errors
+</OnboardingOption>
+<OnboardingOption isStep>
+## Capture React Errors
 
 To make sure Sentry captures all your app's errors, configure error handling based on your React version.
 
@@ -159,8 +168,10 @@ import * as Sentry from "@sentry/react";
   [here](features/error-boundary/#manually-capturing-errors).
 </Alert>
 
-<OnboardingOption optionId="performance">
-## Step 4: Set Up React Router
+</OnboardingOption>
+
+<OnboardingOption optionId="performance" isStep>
+## Set Up React Router
 If you're using `react-router` in your application, you need to set up the Sentry integration for your specific React Router version to trace `navigation` events.\
 Select your React Router version to start instrumenting your routing:
 
@@ -169,43 +180,34 @@ Select your React Router version to start instrumenting your routing:
 - [Older React Router versions](features/react-router)
 - [TanStack Router](features/tanstack-router)
 
-## Step 5: Capture Redux State Data (Optional)
-
 </OnboardingOption>
 
-<OnboardingOption optionId="performance" hideForThisOption>
-  ## Step 4: Capture Redux State Data (Optional)
-</OnboardingOption>
+<OnboardingOption isStep>
+## Capture Redux State Data (Optional)
 
 To capture Redux state data, use `Sentry.createReduxEnhancer` when initializing your Redux store.
 
 <PlatformContent includePath="configuration/redux-init" />
 
-<OnboardingOption optionId="performance">
-  ## Step 6: Add Readable Stack Traces With Source Maps (Optional)
-</OnboardingOption>
-<OnboardingOption optionId="performance" hideForThisOption>
-  ## Step 5: Add Readable Stack Traces With Source Maps (Optional)
 </OnboardingOption>
 
+<OnboardingOption isStep>
+## Add Readable Stack Traces With Source Maps (Optional)
+
 <PlatformContent includePath="getting-started-sourcemaps-short-version" />
 
-<OnboardingOption optionId="performance">
-  ## Step 7: Avoid Ad Blockers With Tunneling (Optional)
-</OnboardingOption>
-<OnboardingOption optionId="performance" hideForThisOption>
-  ## Step 6: Avoid Ad Blockers With Tunneling (Optional)
 </OnboardingOption>
 
+<OnboardingOption isStep>
+## Avoid Ad Blockers With Tunneling (Optional)
+
 <PlatformContent includePath="getting-started-tunneling" />
 
-<OnboardingOption optionId="performance">
-  ## Step 8: Verify Your Setup
-</OnboardingOption>
-<OnboardingOption optionId="performance" hideForThisOption>
-  ## Step 7: Verify Your Setup
 </OnboardingOption>
 
+<OnboardingOption isStep>
+## Verify Your Setup
+
 Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.
 
 ### Issues
@@ -230,6 +232,8 @@ To verify that Sentry captures errors and creates issues in your Sentry project,
 
 <PlatformContent includePath="getting-started-browser-sandbox-warning" />
 
+</OnboardingOption>
+
 <OnboardingOption optionId="performance">
 ### Tracing
 
@@ -254,6 +258,8 @@ Open the page in a browser (for most React applications, this will be at localho
 
 </OnboardingOption>
 
+<OnboardingOption>
+
 ### View Captured Data in Sentry
 
 Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear).
@@ -277,3 +283,7 @@ Now's a good time to customize your setup and look into more advanced topics. Ou
 - [Get support](https://sentry.zendesk.com/hc/en-us/)
 
 </Expandable>
+
+</OnboardingOption>
+
+</OnboardingSteps>

docs/platforms/javascript/guides/svelte/index.mdx

@@ -9,7 +9,11 @@ categories:
 
 <PlatformContent includePath="getting-started-prerequisites" />
 
-## Step 1: Install
+<OnboardingSteps>
+
+<OnboardingOption isStep>
+
+## Install
 
 Choose the features you want to configure, and this guide will show you how:
 
@@ -34,8 +38,11 @@ yarn add @sentry/svelte
 ```bash {tabTitle:pnpm}
 pnpm add @sentry/svelte
 ```
+</OnboardingOption>
+
+<OnboardingOption isStep>
 
-## Step 2: Configure
+## Configure
 
 To use the SDK, initialize it in your Svelte entry point before bootstrapping your app. In a typical Svelte project, that is your `main.js` or `main.ts` file.
 
@@ -160,16 +167,25 @@ const app = new App({
 
 export default app;
 ```
+</OnboardingOption>
+
+<OnboardingOption isStep>
 
-## Step 3: Add Readable Stack Traces With Source Maps (Optional)
+## Add Readable Stack Traces With Source Maps (Optional)
 
 <PlatformContent includePath="getting-started-sourcemaps-short-version" />
 
-## Step 4: Avoid Ad Blockers With Tunneling (Optional)
+</OnboardingOption>
+
+<OnboardingOption isStep>
+## Avoid Ad Blockers With Tunneling (Optional)
 
 <PlatformContent includePath="getting-started-tunneling" />
 
-## Step 5: Verify Your Setup
+</OnboardingOption>
+
+<OnboardingOption isStep>
+## Verify Your Setup
 
 Let's test your setup and confirm that Sentry is working correctly and sending data to your Sentry project.
 
@@ -205,6 +221,8 @@ To verify that Sentry captures errors and creates issues in your Sentry project,
 
 <PlatformContent includePath="getting-started-browser-sandbox-warning" />
 
+</OnboardingOption>
+
 <OnboardingOption optionId="performance">
 ### Tracing
 
@@ -244,6 +262,7 @@ Open the page in a browser and click the button to trigger a frontend error and
 
 </OnboardingOption>
 
+<OnboardingOption>
 ### View Captured Data in Sentry
 
 Now, head over to your project on [Sentry.io](https://sentry.io/) to view the collected data (it takes a couple of moments for the data to appear).
@@ -267,3 +286,7 @@ Now's a good time to customize your setup and look into more advanced topics. Ou
 - [Get support](https://sentry.zendesk.com/hc/en-us/)
 
 </Expandable>
+
+</OnboardingOption>
+
+</OnboardingSteps>

src/components/onboarding/index.tsx

@@ -142,25 +142,42 @@ const validateOptionIds = (options: Pick<OnboardingOptionType, 'id'>[]) => {
 
 export function OnboardingOption({
   children,
-  optionId,
+  optionId = 'all',
   hideForThisOption,
+  isStep = false,
 }: {
-  children: React.ReactNode;
-  optionId: OptionId;
+  children: ReactNode;
+  optionId: OptionId | 'all';
   hideForThisOption?: boolean;
+  isStep?: boolean;
 }) {
-  validateOptionIds([{id: optionId}]);
+  if (optionId !== 'all') {
+    // Allow not passing an optionId when isStep is true
+    validateOptionIds([{id: optionId}]);
+  }
+  const className = [hideForThisOption ? 'hidden' : '', isStep ? 'onboarding-step' : '']
+    .filter(Boolean)
+    .join(' ');
+
   return (
     <div
       data-onboarding-option={optionId}
       data-hide-for-this-option={hideForThisOption}
-      className={hideForThisOption ? 'hidden' : ''}
+      className={className}
     >
       {children}
     </div>
   );
 }
 
+/**
+ * Wrapper component that provides CSS counter context for numbered onboarding steps
+ * @param children - OnboardingOption components that should be numbered as steps
+ */
+export function OnboardingSteps({children}: {children: ReactNode}) {
+  return <div className="onboarding-steps">{children}</div>;
+}
+
 /**
  * Updates DOM elements' visibility based on selected onboarding options
  */

src/mdxComponents.ts

@@ -18,7 +18,11 @@ import {GuideGrid} from './components/guideGrid';
 import {JsBundleList} from './components/jsBundleList';
 import {LambdaLayerDetail} from './components/lambdaLayerDetail';
 import {LinkWithPlatformIcon} from './components/linkWithPlatformIcon';
-import {OnboardingOption, OnboardingOptionButtons} from './components/onboarding';
+import {
+  OnboardingOption,
+  OnboardingOptionButtons,
+  OnboardingSteps,
+} from './components/onboarding';
 import {OrgAuthTokenNote} from './components/orgAuthTokenNote';
 import {PageGrid} from './components/pageGrid';
 import {ParamTable} from './components/paramTable';
@@ -84,6 +88,7 @@ export function mdxComponents(
     PlatformSdkPackageName,
     OnboardingOption,
     OnboardingOptionButtons,
+    OnboardingSteps,
     RelayMetrics,
     SandboxLink,
     SignInNote,