Platforms & Guides

Platform content lives in docs/platforms and follows some specific rules to generate content. The content is rendered using the same features as all other pages, but has some additional functionality exposed to clone content and encapsulate platforms as portals.

Directory structure has meaning within the platforms directory, and looks something akin to:

Copied
[platformName]/
  child.mdx
  childTwo/
    index.mdx
  common/
    aSharedPage.mdx
  guides/
    [guideName]/
      uniqueChild.mdx
      childTwo/
        index.mdx

Platforms will generate a list of "guides" that inherit all content within common. Given the above example, we end up with a variety of semi-duplicated URLs:

Copied
/platforms/platformName/
/platforms/platformName/config.yml
/platforms/platformName/child/
/platforms/platformName/childTwo/
/platforms/platformName/aSharedPage/
/platforms/platformName/guides/guideName/
/platforms/platformName/guides/guideName/config.yml
/platforms/platformName/guides/guideName/child/
/platforms/platformName/guides/guideName/uniqueChild/
/platforms/platformName/guides/guideName/childTwo/
/platforms/platformName/guides/guideName/aSharedPage/

This is generated by inheriting all content with the common/ directory, then adding (or overriding with) content from the siblings (or children as we'd call them). In the above example, you'll see aSharedPage is loaded at two different URLs, and childTwo is overwritten by guideName.

The sidebar on platform pages (handled by <PlatformSidebar>) will generate with the Guide, or the Base Platform being the primary section, in addition to a list of other guides available in a section below it. This means that all content is focused on the current guide (usually a framework) they're in, ensuring ease of navigation.

Configuration is read (in order) from [namespace]/index.mdx and [namespace]/config.yml. This means that a platform's index can be fully rendered via a common page.

Valid configuration attributes are:

title

The display name for a platform.

supportLevel

The level of support. production (default) or community

caseStyle

The casing style for code samples. canonical (default), camelCase, snake_case, or PascalCase

categories

A list of categories for future support. Known values are browser, mobile, desktop, and server.

fallbackPlatform

The key to use for defaults. Can use full key syntax of platformName or platformName.guideName.

sdk

The name of the SDK, if available. Used to embed SDK information on pages.

aliases

A list of aliases for this platform. For example, "Cocoa" might apply to Apple, or "C#" might apply to .NET.

showIntegrationsInSearch

Whether to show integrations in the search results on the home page.

Note: This is only applicable to platforms that have no guides like Python.

Shared (duplicated) content within an SDK (platform) is available in the src/platforms/[platformName]/common/ folder.

All of this content will be automatically duplicated within every guide. This leverages components like PlatformContent which can automatically substitute content out.

Sometimes a page may not make sense within the context of a given guide. To control this, you can use the supported and notSupported frontmatter on common pages in platforms.

Page visibility works similar to the supported/notSupported attributes in other platform components (such as PlatformSection).

For example, if you wanted to make hide the content for a platform by default, but enable it for a guide, you can do that like so:

Copied
---
supported:
  - native.wasm
notSupported:
  - native
---

If the page you're conditionally hiding has subpages, you'll need to add the supported/notSupported annotations to the subpages as well.

There are a number of components that aid the development of platform specific pages, as well as behave differently when a platform is active. For more information, see components.

We differentiate platforms by language and developer interaction. A top-level SDK is considered a platform. A platform may have guides for frameworks that it supports, and these guides often inherit much of their content from their parent platform.

In general, use this decision tree:

  • Is it a new programming language? -> new platform
  • Does it require a separate SDK or way of sending data to Sentry? -> new platform
  • Does it count as a "platform" -> new platform
  • Otherwise -> add it as a Guide to an existing platform

JavaScript is a top-level SDK because the frameworks that it supports share much of the same content.

On the other hand, Android and Java have very little overlap. As a result, they are both top level platforms.

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").