Skip to main content
Version: Next

Documentation

The Tenzir documentation resides inside our main GitHub repository in /web/docs. We use Docusaurus as website framework.

Build and view locally​

To view the entire site (including the documentation) locally, change to the /web directory and invoke yarn, or to be on the safe side, yarn install --frozen-lockfile to avoid pollution from global dependencies. Then build and serve the site via:

yarn start

Browse to http://localhost:3000/ to view the site. Docusaurus should spawn your default browser automatically upon invoking yarn start.

Write content​

Docusaurus uses an enhanced flavor of Markdown that allows for embedding richer content elements, such as:

We encourage making judicious use of these extras for an optimal reading experience.

Edit diagrams​

We use Excalidraw as primary tool to create sketches of architectural diagrams. It is open source and has a neat collaboration feature: the ability to embed the source code of the sketch into the exported PNG or SVG images.

Our editing workflow looks as follows:

  1. Open https://excalidraw.com and click Upload in the top left
  2. Select the SVG you would like to edit
  3. Make your edits in Excalidraw
  4. Uncheck the box "Background" to ensure a transparent background.
  5. Re-export the drawing as SVG and check the box "Embed scene"

The last part is crucial: If you don't check "Embed scene" we will no longer be able to recover the original diagram source.

Filename Convention

By convention, we export all SVGs with embedded Excalidraw source with the filename extension *.excalidraw.svg.

Cater to dark mode​

The Excalidraw workflow above already respects dark mode. You only need to include the generated SVG as follows:

![Image Description](/path/to/diagram.excalidraw.svg)

For non-Excalidraw images, you must provide two versions, one for light and one for dark mode. We use the same CSS that GitHub supports to render them conditionally, i.e., #gh-dark-mode-only and #gh-light-mode-only.

Here's an example to include one image that exists in two variants:

![Image Description](/path/to/dark.png#gh-dark-mode-only)
![Image Description](/path/to/light.png#gh-light-mode-only)

Scale images​

We're making use of the alt text in Markdown images in combination with some CSS3 features to specify a maximum width:

![alt #width500](/path/to/img)

The suffix #width500 gets picked up by the following CSS:

img[alt$="#width500"] {
  max-width: 500px;
  display: block;
}

We currently support the following classes:

  • #width300
  • #width400
  • #width500
  • #width600

This should hopefully cover the majority of use cases.