MDX Components

Alert

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

<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

Render an Arcade embed.

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

Attributes:

• src (string) - the URL of the Arcade embed

Expandable

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

const foo = 'bar';

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

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:

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

```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):

function foo() {
  let lookat = "me";
  return "bar";
}

You can also highlight diffs using the diff language:

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

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

ConfigKey

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

<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

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.

---
# 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

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

<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

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

<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

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

<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

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

<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

If you're writing product feature specific docs, you can specify code block onboardingOptions metadata:

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

<OnboardingOptionButtons
  options={["error-monitoring", "profiling", "performance"]}
/>

• options can either be either an object of this shape:

{
  id: 'error-monitoring' | 'performance' | 'profiling' | 'session-replay',
  disabled: boolean,
  checked: boolean
}

or a string (one of these ids 👆) for convenience when using defaults.

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

Example (output of the above):

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",
	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

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

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

Example:

• toggle the performance option above to see the effect:

  JSX

  Copied

  <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

  Copied

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