Sentry Documentation

The Sentry documentation is a static site, generated with Gatsby.

Getting started

You will need Volta and pre-commit installed. If you don't have opinions about the process, this will get you going:

# Install Homebrew and everything mentioned above
$ bin/bootstrap

Once you have the required system dependencies:

# Install or update application dependencies
$ make

Now run the development webserver:

$ yarn start

You will now be able to access docs via http://localhost:3000.

Markdown Documentation

Documentation is written in Markdown (via Remark) and MDX.

Read the quick reference

Redirects

Redirects are supported via yaml frontmatter in .md and .mdx files:

---
redirect_from:
  - /performance-monitoring/discover/
---

These will be generated as both client-side (using an empty page with a meta tag) and server-side (nginx rules).

Wizard Pages

A number of pages exist to provide content within Sentry installations. We refer to this system as the Wizard. These pages are found in Gatsby's wizard content directory, and are rendered and exported to a JSON file for use within the getsentry/sentry application.

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

---
name: Platform Name
doc_url: Permalink for this page
type: framework
support_level: production
---

This is my  content.

Search

Search is powered by Algolia, and will index all content in /docs/ that is Markdown or MDX formatted.

It will not index documents with any of the following in their frontmatter:

draft: true
noindex: true

Notes on Markdown vs MDX

🙏 that MDX v2 fixes this.

MDX has its flaws. When rendering components, any text inside of them is treated as raw text (not markdown). To work around this you can use the <markdown> tag, but it also has its issues. Generally speaking, put an empty line after the opening tag, and before the closing tag.

// don't do this as parsing will hit weird breakages
<markdown>
foo bar
</markdown>

// do this
<markdown>

foo bar

</markdown>

Platform / SDK Docs

The current generation platform content lives in src/platforms and follows some specific rules to generate content. These rules are enforced via the directory structure:

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

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

/platforms/platformName/
/platforms/platformName/child/
/platforms/platformName/childTwo/
/platforms/platformName/aSharedPage/
/platforms/platformName/guides/guideName/
/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.

Globally Shared Content

In addition to platform-shared content (via common/) you can also defined globally shared content (shared by all platforms and guides). This is done by placing the content into the top-level /platforms/common/ path. It works very much the same as the platform-level common content.

Extended Markdown Syntax

Variables

A transformation is exposed to both Markdown and MDX files which supports processing variables in a Django/Jekyll-style way. The variables available are globally scoped and configured within gatsby-config.js (via gatsby-remark-variables).

For example:

JavaScript SDK: {{ packages.version('sentry.browser.javascript') }}

In this case, we expose packages as an instance of PackageRegistry which is why there is a packages.version function available. Additional, we expose a default context variable of page which contains the frontmatter of the given markdown node. For example, {{ page.title }}.

When a function call is invalid (or errors), or doesn't match something in the known scope, it will simple render it as a literal value instead. So for example:

setFingerprint('{{ default }}')

Will render as:

setFingerprint('{{ default }}')

This is because there is no entity scoped to default in the template renderer. Additionally - in this case - we also add the default expression to the exclusion list in our configuration, as it is commonly use in our documentation.

`packages`

The packages helper is an instance of PackageRegistry and exposes several methods.

`packages.version`

Returns the latest version of the given package.

packages.version('sentry.javacript.browser')

You may also optionally specify a fallback for if the package isnt found (or theres an upstream error):

packages.version('sentry.javacript.browser', '1.0.0')

`packages.checksum`

Returns the checksum of a given file in a package.

packages.checksum('sentry.javacript.browser', 'bundle.min.js', 'sha384')

Extended MDX Syntax

We expose several default tags to aid with documentation.

Alert

Render an alert callout.

Attributes:

title (string)
level (string)
dismiss (boolean)

<Alert level="info" title="Note"><markdown>

This is an alert

</markdown></Alert>

ConfigKey

Render a heading with a configuration key in the correctly cased format for a given platform.

If content is specified, it will automatically notate when the configuration is unsupported for the selected platform.

Attributes:

name (string)
platform (string) - defaults to the platform value from the query string
supported (string[])
notSupported (string[])

<ConfigKey name="send-default-pii" notSupported={["browser", "node"]}><markdown>

Description of send-default-pii

</markdown></ConfigKey>

Code Blocks

Consecutive code blocks will be automatically collapsed into a tabulated container. This behavior is generally useful if you want to define an example in multiple languages:

```javascript
function foo() { return 'bar' }
```

```python
def foo():
  return 'bar'
```

Some times you may not want this behavior. To solve this you can either break up the code blocks with some additional text, or you can use the <Break /> component.

Additionally code blocks also support tabTitle and filename properties:

```javascript {tabTitle: Hello} {filename: index.js}
var foo = "bar";
```

Linting

We use prettier to format our code. Run prettier if you get linting errors in CI.

yarn prettier:fix

If you want to run prettier on mdx and markdown files, run

yarn prettier:fix:all

mmcgrana / sentry-docs