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

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.

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

Read the quick reference

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

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 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

🙏 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>

If you want to create new docs for SDKs you should start by choosing an SDK to copy from and change the parts necessary. Start by calling

yarn sdk:copy javascript angular

This for example will take the src/sdks/javascript content and symlink everything into src/sdks/angular. Since all the files are symlinks the content will be the same. Files that have different content in the new folder need to be deleted and created manually again to be able to change the content. If you change something in the symlink it will change the original file.

Also open src/components/sidebar.js search for a variable named: newSdkDocs which should look something like this

const newSdkDocs = ['javascript', 'angular'];

This will add the newly created SDK docs to the sidebar.