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:
- 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.
- If required, add an icon to
platformicons
. If added, you also need to add a platform to icon mapping insrc/platformIcon.tsx
on Sentry, bump the package version and update its version in repositories that use it (sentry
anddocs
). - 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 tosrc/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
instatic/app/components/events/interfaces/spans/utils.tsx
.
- Add it to the corresponding category in
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:
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
---
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.
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").