README.md.erb

# Documentation

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

## Installation and usage (Docker)

You can simply use Docker this way:

```bash
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

```bash
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)

```bash
cd website
yarn
```

### Starting the website locally

```bash
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:

```bash
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 rounded corners
- No browser header

Preferred screenshot tools:
- Flameshot
- Skitch (only MacOs)

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!