Veridise Documentation

This repository hosts the documenstation site to be used for all Veridise tools. The website is built using Docusaurus 3.

Prerequisites

Ensure you have a supported LTS version of Node.js (like v20 or newer). Alternatively, install Nix, as this repository provides a Nix flake definition that will install the correct version of Node.js and other dependencies

Building the site for development

nix develop # optional, if using Nix
npm ci
npm run start

The second command starts a local development server and opens up a browser window. Most changes are reflected live without having to restart the server. Some changes will require you to restart the server, usually when you cut new versions, rename folders, or modify React code.

Cutting a new version of documentation

By default, the documentation in unversioned folders like orca is considered bleeding-edge documentation and is assigned a "Next" version. Suppose you want to cut a new version of OrCa documentation, like version 1.0. In this case, you can run the following command.

npm run docusaurus docs:version:orca 1.0

This will create an orca_versioned_docs folder and inside of it, we will have a list of folders, each corresponding to a distinct version of orca. Note that you may need to restart your dev server in order to see changes reflected.

Then you should be able to browse http://localhost:3000/orca/1.0/.

Note: you should avoid having to modify versioned docs as best as you can. Use the unversioned docs folders to add new information.

Adding documentation

This is as simple as writing a markdown file directly in one the tools folders (such as orca). The unversioned docs folders are usually reserved for the "Next" version of OrCa. This is where all bleeding edge documentation typically goes into. When tool releases are cut, you will also revise documentation and cut a release of it.

Note that "Next" version of docs do not have to be exposed publically. For details, refer to Docusaurus documentation here.

Ordering items on sidebar

Using the file system

By default, Docusaurus will list your documents in lexicographical order. This means if the orca folder has two documents A.md and Z.md, then Docusaurus will display "A" on top of "Z".

If you would like "Z" to appear before "A", you can prefix the files with a number, like 01-Z.md and 02-A.md.

Using the sidebars JSON

You may have noticed there is a "versioned sidebars" folder lingering around. This folder contains a bunch of JSON files where you get to choose how to explicitly order documents. For details, refer to the official Docusaurus documentation.

Subsections in sidebar

Sometimes a single document is too small to fit dozens of sections worth of stuff inside. In this case, you can make a folder with any title you want, then add extra markdown files inside. A sidebar item will be automatically generated and it will have an expansion icon.

Developer Notes

Search bar code was automatically generated by the following command

npm run swizzle docusaurus-lunr-search SearchBar -- --eject --danger

All PRs are checked for consistent formatting. This repository uses Prettier as a formatter. Checks will fail if Prettier detects inconsistent formatting. We recommend installing an editor plugin that runs Prettier on save. Otherwise, make sure to run npm run format before submitting a PR.

Deployment notes

A Dockerfile exists for creating a rootless Docker image hosting a production build of the documentation site. You may build the image with the following command.

docker build -t veridise/docs:latest .

The site is served with a rootless Nginx service, which binds to port 8080. Thus to run the docker image locally, you will need to expose port 8080 like so.

docker run -d -p 3000:8080 veridise/docs:latest

Deployment environments

When changes are merged to main branch, the docs deployment is auto-updated in the dev cluster. The endpoint to access it is: https://docs.veridise.tools