Onboarding Wizard

The docs repository is responsible for a piece of functionality in the Sentry product most commonly referred to as the Wizard. More precisely, the product pulls in documentation about SDK configuration in part of its project creation / onboarding process.

The content for the onboarding wizard is located in src/wizard, and follows slightly different rules than other pages:

  • It is markdown only. MDX is not currently supported.
  • It is exported as plain HTML (encoded as JSON), thus styles need to exist within Sentry itself.
  • The exposed frontmatter is specific to the wizard.

To add a guide to a platform:

  1. Write the guide, following both the guidelines of the Directory Structure and Page Format as well as the examples that currently exist in the directory; the most up to date is typically the wizard for the browser. Note that you do not directly copy the Getting Started page, as the context of this content differs.
  2. If required, add an icon to platformicons. If added, you also need to add a platform to icon mapping in src/platformIcon.tsx on Sentry, bump the package version and update its version in repositories that use it (sentry and docs).
  3. Add the platform to Sentry:
    • Add it to the corresponding category in static/app/data/platformCategories.
    • Add the platform to tests/fixtures/integration-docs/_platforms. Note that you don’t have to add it to src/sentry/integration-docs, since this is automatically generated when the platform assets are built.
    • It may be required to be added to platform-specific places, such as isEventFromBrowserJavaScriptSDK in static/app/components/events/interfaces/spans/utils.tsx.

If after following these steps the guide isn’t on Sentry, you may need to update the platform assets by running make build-platform-assets.

The directory structure directly influences how content is exposed within onboarding. It takes the form of:

Copied
src/wizard
src/wizard/{platform}/index.md
src/wizard/{platform}/{guide}.md

The index.md is exposed as the root platform instructions, and {guide}.md is exposed as a child integration of the platform. This functions similarly to the platform pages.

Each page consists of some wizard-specific frontmatter, as well as a markdown body:

src/wizard/platform/index.md
Copied
---
name: Platform Name
doc_url: Permalink for this page
type: framework
support_level: production
---

This is my content.

Wizard content is only supported with native markdown (not MDX), thus only with a .md extension.

Help improve this content
Our documentation is open source and available on GitHub. Your contributions are welcome, whether fixing a typo (drat!) or suggesting an update ("yeah, this would be better").