Documentation

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

Installation and usage (Docker)

You can simply use Docker this way:

docker run -it --rm -v $(pwd):/mnt/documentation -p 3000:3000 qoveryrd/doc:0.2.2 /mnt/documentation/scripts/docker.sh

Important notes for Mac users:

• Switch to osxfs for file sharing in Docker Desktop settings (Preferences -> General -> Choose file sharing implementation for your containers -> osxfs)
• Add environment variable IS_DOCKER_ON_MAC=1 to the docker run command

docker run -it --rm -v $(pwd):/mnt/documentation -p 3000:3000 -e IS_DOCKER_ON_MAC=1 qoveryrd/doc:0.2.2 /mnt/documentation/scripts/docker.sh

Open a browser to http://localhost:3000

Installation and usage (Local)

Installation (website)

cd website
yarn

Starting the website locally

cd website
yarn start

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

Updating documentation, guides and articles

First, install Ruby gems used for markdown generation in scripts folder:

cd scripts
bundle install

Most of the markdown is generated using Ruby templates. You should never update the markdown files - instead, update the Ruby template file.

Markdown is generated using ERB (Embedded RuBy). Instead of editing .md files directly, remember to apply your changes to some_doc.md.erb and then generate markdown by running make generate USE_CONTAINER=none in the root folder of the documentation repository.

Running make generate USE_CONTAINER=none will apply your changes to all affected markdown files. The make command should be executed in the root folder of this repository. Commit, push & create a PR after running the make generate USE_CONTAINER=none with markdown files generated by the templating system.

If you want to have live update writing (the web ui is updated on any save), you can use this:

./scripts/live_update.sh

Screenshot guidelines

• No background
• No browser header

Preferred screenshot tools:

• Using QuickTime with Arc browser in full-screen mode (light theme) on a Mac without an external monitor. The aim is to have a 16:10 screenshot.

Alternatives:

• Flameshot
• Skitch (only MacOs)

To hide sensitive data. Install this extension to blur some text.

To generate the badge images, you can use this online tool https://img.shields.io/badge/helm-808080. Modify helm-808080 with the text and color of your choice.

Example

To update the Getting Started page in the docs, update the website/docs/getting-started.md.erb instead of website/docs/getting-started.md file (see the difference in .erb file extension). After making changes to the template, run make generate USE_CONTAINER=none in the root folder of the repository. The last step - commit and push your changes, open a PR, and wait for your changes to go live!