feat: onboarding options on getting started pages (#10130)

* feat: onboarding options on getting started pages

* better node filter

* a faster node filter

* denser options UI

* fix: don't copy lines with `display: none;`

* add Golang/gin performance onboarding option example

* adjust option checkbox size

* gain more vertical space around onboarding options buttons

* document option `id`

* feat: onboarding options tooltips

* skip formatting codeblocks with onboarding options

* sticky onboarding option buttons

* move onboarding option buttons immediately bellow ##install

* rename OnboardingOptionButtons component (remove double plural)

* change accidental h1 into h2

* fix sticky element top distance

* refactor: simplify option syntax

* default onboarding options to checked

* adjust option buttons sticky position

* tooltip styles

* wrap option buttons on mobile

* add docs

* make onboarding options syntax play nice with other elements on
code block metadata

* better Regex for onboarding options meta data

* [getsentry/action-github-commit] Auto commit

* full width/bigger option buttons on mobile

* add note about option id with a hyphen

* use JSON syntax for onboarding options metadata

* update example in module doc

* animate onboarding options into view

* disable `error-monitoring` option by default

* fix typo

* update docs

---------

Co-authored-by: getsantry[bot] <66042841+getsantry[bot]@users.noreply.github.com>

Author: a-hariti

docs/contributing/pages/components.mdx

@@ -242,3 +242,110 @@ Attributes:
 - `supported` (string[])
 - `notSupported` (string[])
 - `noGuides` (boolean) - hide this on all guides (takes precedence over `supported`/`notSupported`)
+
+## Onboarding Options
+
+If you're writing product feature specific docs, you can specify code block `onboardingOptions` metadata:
+
+````markdown
+```go {"onboardingOptions": {"performance": "13-17"}}
+// your code here
+```
+````
+
+the general syntax is `{"onboardingOptions": {"feature": "range"}}` where `feature` is the feature id
+and `range` is the corresponding line range (similar to the line highlighting syntax).
+
+You can specify multiple features by separating them with a comma:
+
+`{"onboardingOptions": {"performance": "13-17", "profiling": "5-6"}}`
+
+The range visibility will be controlled by the `OnboardingOptionButtons` component:
+
+````jsx diff
+<OnboardingOptionButtons
+  options={[
+    'error-monitoring',
+    "performance"
+  ]}
+/>
+````
+
+- `options` can either be either an object of this shape:
+
+```typescript
+{
+  id: 'error-monitoring' | 'performance' | 'profiling' | 'session-replay',
+  disabled: boolean,
+  checked: boolean
+}
+```
+or a string (one of these `id`s 👆) for convenience when using defaults.
+
+<Alert level="warning" title="Important">
+  The underlying implementation relies on the `onboardingOptions` metadata in the code blocks to be valid JSON syntax.
+</Alert>
+
+- default values: `checked: false` and `disabled: false` (`true` for `error-monitoring`).
+
+Example (output of the above):
+
+<OnboardingOptionButtons
+  options={[
+    {id: 'error-monitoring', disabled: true},
+    "performance"
+  ]}
+  dontStick
+/>
+
+```go {"onboardingOptions": {"performance": "13-17"}}
+import (
+	"fmt"
+	"net/http"
+
+	"github.com/getsentry/sentry-go"
+	sentrygin "github.com/getsentry/sentry-go/gin"
+	"github.com/gin-gonic/gin"
+)
+
+// To initialize Sentry's handler, you need to initialize Sentry itself beforehand
+if err := sentry.Init(sentry.ClientOptions{
+	Dsn: "___PUBLIC_DSN___",
+	EnableTracing: true,
+	// Set TracesSampleRate to 1.0 to capture 100%
+	// of transactions for performance monitoring.
+	// We recommend adjusting this value in production,
+	TracesSampleRate: 1.0,
+}); err != nil {
+	fmt.Printf("Sentry initialization failed: %v\n", err)
+}
+
+// Then create your app
+app := gin.Default()
+
+// Once it's done, you can attach the handler as one of your middleware
+app.Use(sentrygin.New(sentrygin.Options{}))
+
+// Set up routes
+app.GET("/", func(ctx *gin.Context) {
+	ctx.String(http.StatusOK, "Hello world!")
+})
+
+// And run it
+app.Run(":3000")
+```
+
+You can conditionally render content based on the selected onboarding options using the
+`OnboardingOption` component
+
+Example (toggle the `performance` option above to see the effect):
+
+<OnboardingOption optionId="performance">
+
+```jsx
+<OnboardingOption optionId="performance">
+  This code block is wrapped in a `OnboardingOption` component and will only
+  be rendered when the `performance` option is selected.
+</OnboardingOption>
+```
+</OnboardingOption>

docs/platforms/go/guides/gin/index.mdx

@@ -9,6 +9,13 @@ For a quick reference, there is a [complete example](https://github.com/getsentr
 
 ## Install
 
+<OnboardingOptionButtons
+  options={[
+    'error-monitoring',
+    'performance',
+  ]}
+/>
+
 ```bash
 go get github.com/getsentry/sentry-go/gin
 ```
@@ -17,7 +24,7 @@ go get github.com/getsentry/sentry-go/gin
 
 <SignInNote />
 
-```go
+```go {"onboardingOptions": {"performance": "13-17"}}
 import (
 	"fmt"
 	"net/http"

docs/platforms/php/index.mdx

@@ -21,6 +21,14 @@ This Sentry PHP SDK provides support for PHP 7.2 or later. If you are using our
 
 ## Install
 
+<OnboardingOptionButtons
+  options={[
+    'error-monitoring',
+    'performance',
+    'profiling',
+  ]}
+/>
+
 Sentry captures data by using an SDK within your application’s runtime. These are platform-specific and allow Sentry to have a deep understanding of how your application works.
 
 Install the SDK using [Composer](https://getcomposer.org/).
@@ -29,24 +37,42 @@ Install the SDK using [Composer](https://getcomposer.org/).
 composer require sentry/sentry
 ```
 
-## Configure
+<OnboardingOption optionId="profiling">
+
+Install the Excimer extension via PECL:
+
+```bash
+pecl install excimer
+```
 
-After you’ve completed setting up a project in Sentry, Sentry will give you a value which we call a DSN or Data Source Name. It looks a lot like a standard URL, but it’s just a representation of the configuration required by the Sentry SDKs. It consists of a few pieces, including the protocol, public key, the server address, and the project identifier.
+The Excimer PHP extension supports PHP 7.2 and up. Excimer requires Linux or macOS and doesn't support Windows. For additional ways to install Excimer, [see docs](/platforms/php/profiling/#installation).
+
+</OnboardingOption>
+
+## Configure
 
 To capture all errors, even the one during the startup of your application, you should initialize the Sentry PHP SDK as soon as possible.
 
 <SignInNote />
 
-```php
-\Sentry\init(['dsn' => '___PUBLIC_DSN___' ]);
+```php {"onboardingOptions": {"performance": "3-4", "profiling": "5-6"}}
+\Sentry\init([
+  'dsn' => '___PUBLIC_DSN___' ,
+  // Specify a fixed sample rate
+  'traces_sample_rate' => 1.0,
+  // Set a sampling rate for profiling - this is relative to traces_sample_rate
+  'profiles_sample_rate' => 1.0,
+]);
 ```
 
-## Usage
+## Verify
+
+In PHP you can either capture a caught exception or capture the last error with captureLastError.
 
 ```php
 try {
-    $this->functionFailsForSure();
+  $this->functionFailsForSure();
 } catch (\Throwable $exception) {
-    \Sentry\captureException($exception);
+  \Sentry\captureException($exception);
 }
 ```

package.json

@@ -67,6 +67,7 @@
     "next-auth": "^4.24.5",
     "next-mdx-remote": "^4.4.1",
     "nextjs-toploader": "^1.6.6",
+    "parse-numeric-range": "^1.3.0",
     "platformicons": "^5.10.9",
     "prism-sentry": "^1.0.2",
     "prismjs": "^1.27.0",

src/components/codeBlock/index.tsx

@@ -30,8 +30,7 @@ export function CodeBlock({filename, language, children}: CodeBlockProps) {
       return;
     }
 
-    let code =
-      codeRef.current.textContent || codeRef.current.innerText.replace(/\n\n/g, '\n');
+    let code = codeRef.current.innerText.replace(/\n\n/g, '\n');
 
     // don't copy leading prompt for bash
     if (language === 'bash' || language === 'shell') {

src/components/docPage/type.scss

@@ -1,5 +1,4 @@
 .prose {
-
   h1,
   h2,
   h3,
@@ -140,9 +139,54 @@
     }
   }
 
-  dt+dd {
+  dt + dd {
     margin-bottom: var(--paragraph-margin-bottom);
   }
+
+  [data-onboarding-option].hidden {
+    display: none;
+  }
+  [data-onboarding-option].animate-line {
+    animation:
+      slideLeft 0.2s ease-out forwards,
+      highlight 1.2s forwards;
+  }
+  [data-onboarding-option].animate-content {
+    animation: slideDown 0.2s ease-out forwards;
+  }
+}
+
+@keyframes slideDown {
+  from {
+    transform: translateY(-12px);
+  }
+  to {
+    transform: translateY(0);
+  }
+}
+
+@keyframes slideLeft {
+  from {
+    transform: translateX(-1ch);
+  }
+  to {
+    transform: translateX(0);
+  }
+}
+
+@keyframes highlight {
+  0% {
+    background-color: rgba(255, 255, 255, 0);
+  }
+  10% {
+    background-color: rgba(255, 255, 255, 0.15);
+  }
+  80% {
+    background-color: rgba(255, 255, 255, 0.15);
+  }
+  100% {
+    background-color: rgba(255, 255, 255, 0);
+  }
 }
 
 .sidebar {
@@ -164,7 +208,7 @@ h3.config-key {
 //    <p>This paragraph has a normal bottom margin</p>
 //    <p>This paragraph does not have a bottom margin</p>
 //  </.content-flush-bottom>
-.content-flush-bottom>*:last-child {
+.content-flush-bottom > *:last-child {
   margin-bottom: 0 !important;
 }