Skip to content

Latest commit

 

History

History
96 lines (60 loc) · 3.47 KB

README.md

File metadata and controls

96 lines (60 loc) · 3.47 KB
Raw

Sentry Documentation

The Sentry documentation is a static site, generated by Jekyll.

Getting started

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 http://localhost:9001/.

Using a local Docker container

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.

Development mode

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.

Environment Variables

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.

Markdown documentation

Documentation is written in Markdown, which is parsed by kramdown.

Read the quick reference

While the server is running, you can also view the Markdown styleguide

Custom components

While in dev mode, the sidebar includes documentation for the special tags and includes available for formatting content.

Adding content

The Sentry documentation contains two document types: categories and documents. Documents may have child documents.

Add a category

Categories are manually defined.

  1. 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
  1. Create a markdown file or a folder of markdown files in collections/_documentation/

Add a document

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.