# 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](https://docs.sentry.io/contributing.md), 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:

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

```bash
/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](https://docs.sentry.io/contributing/platforms.md#configuration)

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 Content](https://docs.sentry.io/contributing/platforms.md#shared-content)

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.

### [Page Visibility](https://docs.sentry.io/contributing/platforms.md#page-visibility)

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:

```markdown
---
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.

## [Platform-Specific Components](https://docs.sentry.io/contributing/platforms.md#platform-specific-components)

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](https://docs.sentry.io/contributing/pages/components.md).

## [Delineation](https://docs.sentry.io/contributing/platforms.md#delineation)

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

### [Example](https://docs.sentry.io/contributing/platforms.md#example)

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.

## Pages in this section

- [platform-icons](https://docs.sentry.io/contributing/platforms/platform-icons.md)
- [versioning](https://docs.sentry.io/contributing/platforms/versioning.md)