Ask A BotCommon Content
We provide common content to prevent duplication in our repository. It is provided for all platforms as well as frameworks that rely on a primary platform. In some circumstances, the common content is not valid, or the content varies enough that it must be written specifically to a particular platform or framework. However, if the content is technically correct for a new SDK or framework, there is no need to develop separate content that duplicates the information.
Common content lives in the src/platforms/common/ directory for all platforms, or src/platforms/<platform_name>/common/ for content specific to a platform and its frameworks (which we call guides or children).
Hierarchy
What displays for the user relies upon the hierarchy of content as detailed in our content discussing Platform Portals. In short, a guide's content displays if provided. If not provided, then the platform content displays. If the platform content is not provided, then the common content for all platforms displays.
Tuning Common Content
To ensure that common content can scale as we support more platforms and frameworks, we use include files. These files can range from, most typically, a code sample specific to a platform or framework to information that augments the core content for a specific platform or framework. These platform-specific include files live in src/plaftorm-includes/ and the examples below demonstrate how to use them. We also have platform-agnostic include files which are discussed in our product docs.
The examples below demonstrate how to use platform-specific include files.
Simple Example
Let's look at the src/platforms/common/configuration/environments.mdx file as a simple example of a code sample tuning the common content:
---
title: Environments
sidebar_order: 5
description: "Learn how to configure your SDK to tell Sentry about your environments."
notSupported:
- ruby
---
// frontmatter controls the title of the page, the order in which
the page appears in the lefthand sidebar, provides a description
for the automatically-generated index page, and identifies if
this feature isn't supported by a particular framework, platform,
or SDK.
Sentry automatically creates environments when it receives an event with the
environment tag. Environments are case sensitive. The environment name
can't contain newlines, spaces or forward slashes, can't be the string
"None", or exceed 64 characters. You can't delete environments, but you
can [hide](/product/sentry-basics/environments/#hidden-environments) them.
// Succinct explanation with key technical details and links into the product content.
<PlatformContent includePath="set-environment" />
// An include with a code sample specific to the platform or SDK
being viewed by the user.
Environments help you better filter issues, releases, and user feedback in
the Issue Details page of sentry.io, which you learn more about in our
[documentation that covers using environments](/product/sentry-basics/environments/).
// Succinct explanation of the value of environments, with links to more information.A Second Example, Avoiding Duplication
The common Getting Started content exemplifies further how we avoid duplication in our content with extensive tuning. This file is src/platforms/common/index.mdx:
On this page, we get you up and running with Sentry's SDK, so that
it will automatically report errors and exceptions in your
application.
// Succinct introduction to what's going to happen
<Note>
If you don't already have an account and Sentry project established, head
over to [sentry.io](https://sentry.io/signup/), then return to this page.
</Note>
// An offramp for a user who may have begun reading the content without
having set up an account
<PlatformContent includePath="framework-list" />
// This include creates the default list of frameworks for this platform
## Install
Sentry captures data by using an SDK within your application’s runtime:
<PlatformContent includePath="getting-started-install" />
// An include provides installation instructions specific to the
platform or framework
## Initialize
`init` Sentry as soon as possible in your app. Once this is done, the
Sentry SDK captures all unhandled exceptions.
// Succinct explanation of technical requirement for initialization
and the result
<PlatformContent includePath="getting-started-config" />
// An include explains what the configuration code sample provides
<Note>
We'll automatically assign you a Data Source Name (DSN), which looks like
a standard URL. It's required by Sentry and configures the protocol, public
key, server address, and project identifier. If you forget it, view
_Settings -> Projects -> Client Keys (DSN)_ in sentry.io.
</Note>
// Succinct explanation of a key implementation detail
## Verify
This snippet includes an intentional error, so you can test that everything
is working as soon as you set it up:
// Succinct explanation of the code sample that follows
<PlatformContent includePath="getting-started-verify" />
// An include provides a verification code sample
To view and resolve the recorded error, log into [sentry.io](https://sentry.io)
and open your project. Clicking on the error's title will open a page where
you can see detailed information and mark it as resolved.
// Succinct explanation of what happens as a result of verification, and what
to do in sentry.io
<PageGrid header="Next Steps" nextSteps />
// Automatically generated next steps based on the lefthand sidebarOur 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").