# MDX Components

##

## [Alert](#alert)

Render an alert (sometimes called a callout) to highlight important information.

##### Note

This is an info alert. Use this to emphasize information that users should read.

##### Important

This is a warning alert. Use this to alert users to potential risks they should be aware of.

##### Tip

This is a success alert. Use this to provide optional information that can help users be more successful.

This is an alert without a title. `warning` alerts should always have titles to emphasize their importance.

This is a multi-line alert without a title. Keep information brief and to the point. If this is challenging, consider whether the topic needs documentation on another page or if using the [Expandable](#expandable) component would be a better fit.

##### List

* You can create lists
* and **format** *your* `text`

```markdown
<Alert title="Note">
This is an info alert.
</Alert>
```

Attributes:

* `title` (string) - optional
* `level` (string: `'info' | 'warning' | 'success'`) - optional, defaults to `'info'`

**Where to place alerts:**

Make sure your alerts aren't breaking the flow of the content. For example, don't put an alert between two paragraphs that explain a single concept. Use alerts sparingly; too many alerts on a single page can be overwhelming.

**When to use which alert level:**

* **Info**: Use this to emphasize information that users should read. For example:

  * information needed for users to succeed
  * information you'd typically wrap in a note callout

* **Warning**: Use this to alert users to potential risks they should be aware of. For example:

  * warnings about potential errors, such as ones caused by common oversights in project configuration
  * warnings regarding breaking changes

  Best practices:

  * always use a title with this alert level

* **Success**: Use this to provide optional information that can help users be more successful. For example:

  * information that helps improve an already successful task, such as a link to additional reading material
  * tips for best practices

## [Arcade embeds](#arcade-embeds)

Render an [Arcade](https://arcade.software) embed.

```markdown
<Arcade src="https://demo.arcade.software/v7uhzmdV6Q5PDzoVPAE6?embed&show_copy_link=true" />
```

Attributes:

* `src` (string) - the URL of the Arcade embed

## [Expandable](#expandable)

Render an expandable section to provide additional information to users on demand.

Here's something worth noting

This is an expandable section in an `'info'` alert style. Use this to provide additional information that is helpful, but not crucial.

With permalink

This is an expandable section in an `'info'` alert style with a title wrapped in a link.

This could be important to some users

This is an expandable section in a `'warning'` alert style. Use this to warn users about minor potential risks.

Want some tips to improve something?

This is an expandable section in a `'success'` alert style. Use this to provide optional information that can help users be more successful.

Expandable with a code block

`js const foo = 'bar';`

```markdown
<Expandable title="Here's something worth noting">
  This is an expandable section in an `'info'` alert style.
</Expandable>
```

Attributes:

* `title` (string)
* `permalink` (boolean) - optional: wraps the title in a link and shows it in the table of contents.

**When to use expandables:**

Expandables help keep our documentation clutter-free, allowing users to focus on important information while providing them the option to explore additional relevant details.

For example, use expandables to:

* offer information that is useful to some users but not all, like troubleshooting tips
* provide background information or insights into related concepts

**Best practices**

* Write the expandable title as a question or statement to clarify what users can expect from the content within:

  * Do you want to learn more about these features?
  * Are you using Node.js version 15 or lower?
  * Advanced configuration options for XY use case.

* When you need to share important information that users should read, consider using an [alert](#alert) instead since its content is visible by default.

* Avoid overusing this component and make sure to provide valuable information that is relevant to the current topic.

## [Code Blocks](#code-blocks)

Consecutive code blocks will be automatically collapsed into a tabulated container. This behavior is generally useful if you want to define an example in multiple languages:

````markdown
```javascript
function foo() {
  return "bar";
}
```

```python
def foo():
  return 'bar'
```
````

Sometimes you may not want this behavior. To solve this, you can either break up the code blocks with some additional text, or use the `<Break />` component.

Additionally code blocks also support `tabTitle` and `filename` properties:

````markdown
```javascript {tabTitle: Hello} {filename: index.js}
var foo = "bar";
```
````

You can bring attention to specific lines in a code block using the `{fromLineA-toLineB}` for ranges, or `{lineA,lineB}` for specific lines (or a combination of the two):

```javascript
function foo() {

  let lookat = "me";

  return "bar";
}
```

You can also highlight diffs using the `diff` language:

````markdown
```diff
- minus one
+ plus one
```
````

If you want to preserve syntax highlighting, you can add `diff` metadata to any code block then annotate the diff with `+` and `-`:

```javascript
function foo() {
-  return "bar";
+  return "baz";
}
```

## [ConfigKey](#configkey)

Render a heading with a configuration key in the correctly cased format for a given platform.

If content is specified, it will automatically hide the content when the given `platform` is not selected in context.

```markdown
<ConfigKey name="send-default-pii" notSupported={["javascript"]}>

Description of send-default-pii

</ConfigKey>
```

Attributes:

* `name` (string)
* `platform` (string) - defaults to the `platform` value from the page context
* `supported` (string\[])
* `notSupported` (string\[])

## [PageGrid](#pagegrid)

Render all `next_steps` of this document or default child pages, including their `description` if available.

You can specify `next_steps` in the frontmatter of a page to include them in the grid. It supports relative paths and will automatically resolve them.

```markdown
---
# in the frontmatter of a page:
next_steps:
  - ./child-one
  - ./child-two
  - ../parent/child-three
---

<PageGrid />
```

Attributes:

* `header` (string) - optional header value to include, rendered as an H2

* `nextPages` (boolean) - only render pages which come next based on sidebar ordering

* `exclude` (string\[]) - an array of pages to exclude from the grid. Specify the file name of the page, for example, `"index"` for `index.mdx`.

## [PlatformContent](#platformcontent)

Render an include based on the currently selected `platform` in context.

```markdown
<PlatformContent includePath="sdk-init" />
```

Attributes:

* `includePath` (string) - the subfolder within `/includes` to map to
* `platform` (string) - defaults to the `platform` value from the page context

Some notes:

* When the current platform comes from the page context and no matching include is found, the content will be hidden.

* Similar to `PlatformSection`, you can embed content in the block which will render *before* the given include, but only when an include is available.

* A file named `_default` will be used if no other content matches.

Note: This currently causes issues with tableOfContents generation, so its recommended to disable the TOC when using it.

## [PlatformIdentifier](#platformidentifier)

Render terms in the correct case within the body text of a page (not in code samples) based on the platform case\_style setting:

```markdown
<PlatformIdentifier name="before-send" />
```

For example, if you use `<PlatformIdentifier name="before-send" />`, it will render as:

* `beforeSend` if case\_style=camelCase
* `before_send` if case\_style=snake\_case
* `BeforeSend` if case\_style=PascalCase

This component only works properly in platform pages.

## [PlatformLink](#platformlink)

Useful for linking to platform-specific content when there's not a specific platform already selected.

```markdown
<PlatformLink to="/enriching-events/" />
```

This will direct users to a page where they can choose the platform, and then to the appropriate link. If they're within a page that already has an active platform, it will simply link to the appropriate page and skip the redirect.

## [PlatformSection](#platformsection)

Render a section based on the currently selected `platform` in context. When the platform is not valid, the content will be hidden.

```markdown
<PlatformSection notSupported={["javascript"]}>

Something that applies to all platforms, but not javascript or node.

</PlatformSection>
```

Attributes:

* `platform` (string) - defaults to the `platform` value from the page context
* `supported` (string\[])
* `notSupported` (string\[])
* `noGuides` (boolean) - hide this on all guides (takes precedence over `supported`/`notSupported`)

## [Onboarding Options](#onboarding-options)

If you're writing product feature specific docs, you can specify markers within code blocks that enable or disable certain parts of snippets:

##### warning

Do not copy the following code snippet, the `___PRODUCT_OPTION_START___` and `___PRODUCT_OPTION_END___` markers have an extra character (zero width space) as a workaround to make them show up correctly in the example.

````markdown
```go
  // _​__PRODUCT_OPTION_START___ performance
  // your code here
  // _​__PRODUCT_OPTION_END___ performance
```
````

the syntax uses the standard comment style of the programming language you're documenting. For example:

* TypeScript/JavaScript: `// ___PRODUCT_OPTION_START___ feature`
* Python: `# ___PRODUCT_OPTION_START___ feature`

where `feature` is the feature id (e.g. `performance`, `profiling` or `session-replay`).

The range visibility will be controlled by the `OnboardingOptionButtons` component:

```jsx
<OnboardingOptionButtons
  options={["error-monitoring", "profiling", "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.

##### Important

The underlying implementation relies on the `onboardingOptions` metadata in the code blocks to be valid JSON syntax.

* default values: `checked: false` and `disabled: false` (`true` for `error-monitoring`).

Example (output of the above):

Error Monitoring\[ ]Tracing\[ ]Profiling

```go
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: "https://examplePublicKey@o0.ingest.sentry.io/0",
  //  performance
	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,
  //  performance
  // Adds request headers and IP for users,
  // visit: https://docs.sentry.io/platforms/go/data-management/data-collected/ for more info
  SendDefaultPII: true,
}); 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

Or you can use the `hideForThisOption` prop to hide the content for the selected option.

````markdown
```jsx
<OnboardingOption optionId="profiling" hideForThisOption>
  Hide this section for `profiling` option.
</OnboardingOption>
```
````

Example:

* toggle the `performance` option above to see the effect:

  ```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>;
  ```

* toggle the `profiling` option above to see the effect:

  ```jsx
  <OnboardingOption optionId="profiling" hideForThisOption>
    This code block is wrapped in a `OnboardingOption` component and will
    only be rendered when the `profiling` option is NOT selected.
  </OnboardingOption>;
  ```
