Website

This website is built using Docusaurus 2, a modern static website generator.

Installation

Prerequisites

For this project you need to have installed the following tools:

• NodeJs
• Npm

If the gen_sidebars.py script is going to be used, the following prerequisites are also needed:

• Python => v3.9
  • Pip
  • Pyyaml module

Dependencies

npm install

Local Development

npm start

This command starts a local development server and open up a browser window. Most changes are reflected live without having to restart the server.

npm run gensidebars

If you add new pages to the docs, you can run the above script to generate the configuration for the sidebar of the website.

Build

npm build

This command generates static content into the build directory and can be served using any static contents hosting service.

npm run serve

After building, it is important to test that everything works as intended, and that your build was successful. Run serve to start a server with your newly built project.

Conventions

There are a few conventions that should be followed when working with the documentation repository.

1. When adding images for a guide:
2. Create a folder in static/img/guides/<id-of-new-guide> and place the images there 2. Ensure images aren't too large (no more than 2MB?) 3. Ensure images are in JPEG/JPG format
3. Follow the naming conventions across the repository:
4. File names should be written_in_snake_case
5. Page IDs need to be separated-with-dashes
6. Titles and headings use capital letters for each word with some exceptions (a, to, for, the, etc)
7. Try to have consistent spacing:
8. Lines shouldn't be longer than 120 characters
9. Indented lines are 2 spaces

Deployment

GIT_USER=<Your GitHub username> USE_SSH=true npm deploy

If you are using GitHub pages for hosting, this command is a convenient way to build the website and push to the gh-pages branch.

NOTE: After a deploy, if you're getting a 404, you need to remember to set the GitHub pages redirect domain.