The VAST documentation resides inside our main GitHub
We use Docusaurus as website framework.
Build and view locally
To view the entire site (including the documentation) locally,
change to the
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:
Browse to http://localhost:3000/ to view the site. Docusaurus should spawn
your default browser automatically upon invoking
Docusaurus uses an enhanced flavor of Markdown that allows for embedding richer content elements, such as:
- Callouts/admonitions for block notes, infos, and warnings
- React JSX components via MDX, specifically via the built-in UI component library Infima
- Math equations via KaTeX
We encourage making judicious use of these extras for an optimal reading experience.
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:
- Open https://excalidraw.com and click Upload in the top left
- Select the SVG you would like to edit
- Make your edits in Excalidraw
- Uncheck the box "Background" to ensure a transparent background.
- 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.
By convention, we export all SVGs with embedded Excalidraw source with the
Cater to dark mode
The Excalidraw workflow above already respects dark mode. You only need to include the generated SVG as follows:
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
Here's an example to include one image that exists in two variants:
We're making use of the alt text in Markdown images in combination with some CSS3 features to specify a maximum width:
#width500 gets picked up by the following CSS:
We currently support the following classes:
This should hopefully cover the majority of use cases.