Skip to main content

Documentation

The VAST 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.

This means the editing workflow looks as follows:

  1. Open https://excalidraw.com and click Upload in the top left
  2. Select the PNG or SVG you would like to edit
  3. Make your edits in Excalidraw
  4. Re-export the drawing in size 2x and check the box "Embed scene"

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

Transparent Background

If possible, uncheck the box "Background" to generate a transparent background, as it makes images fit in more seamlessly.

Cater to dark mode

Our setup makes it easy to render different images whether light or dark mode is toggled. We use the same CSS that GitHub supports, 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)