The Sentry documentation is a static site, generated by Jekyll.
You will need Ruby, Bundler, Node.js, and Yarn installed. If you don't have opinions about the process, this will get you going:
# Install Homebrew and everything mentioned above
$ bin/bootstrap
To run the local webserver:
$ bin/server
This will run Bundler to install all the necessary dependencies and then run a webserver at https://localhost:9001/.
If you'd like to avoid installing all those local dependencies, you can run everything in a local Docker container.
Just build and run it like this:
#Build the container:
$ docker build -t sentry:jekyll-local-builder -f Dockerfile.local .
#Run the container:
$ docker run -it -p 9000:4000 -p 35727:35727 -v $(pwd):/sentry/docs --rm sentry:jekyll-local-builder
This will start a local shell inside the container. Afterwards, a simple bin/server
like before will be enough.
There are a number of enhancements in place that are only available when developing locally.
- Numerous optimizations have been made to speed up builds. See [environment-variables] for more info.
- Pressing the ``` key reveals a drawer with meta info for each page.
- The sidebar includes links to documentation of special components available to the docs.
The following variables can be set when using bin/server
. Defaults prefer performance.
FAST_BUILD=true
The master switch. When true, all performance adjustments are enabled. Disable to debug strange behavior.JEKYLL_INCREMENTAL=true
When true, Jekyll only rebuilds pages that have changed. In some cases this can create unpredictable behavior.JEKYLL_ENABLE_PLATFORM_API=false
When false,_platforms/*
will not be generated.
Documentation is written in Markdown, which is parsed by kramdown.
While the server is running, you can also view the Markdown styleguide
While in dev mode, the sidebar includes documentation for the special tags and includes available for formatting content.
The Sentry documentation contains two document types: categories and documents. Documents may have child documents.
Categories are manually defined.
- Add a new entry to src/data/documentation_categories.yml. Order is defined by the order in this document.
# Display name for the category
- title: Category Name
# slug matching a filename in _includes/svg/
icon: category-icon
# A slug for the category. Must match a file or folder in collections/_documentation/
slug: category-slug
- Create a markdown file or a folder of markdown files in collections/_documentation/
Category hierarchy is automatically defined by folder structure. Add a markdown file to a folder within _src/collections/documentation. Order is alphabetical by default, or you may force sorting order by adding an sidebar_order
integer value in the frontmatter of the document.