Preparing the local environment for writing documentation¶

Getting Started¶

We use Markdown with extensions according to the Material for MkDocs reference.

To set up the project for development and testing on your local machine, please follow these steps. Alternatively, you can edit the Markdown files directly on GitHub, open a pull request (PR), and the CI/CD pipeline will manage the build and deployment process after the changes are merged.

For .juvix.md files, which include Juvix code examples, ensure that Juvix is installed. You can install the Juvix plugin for VS Code from the marketplace.

Installing with Python¶

Install prerequisites

The following are the prerequisites to build the website locally:
- Python or higher which includes pip
- Poetry: You can install by running pip install poetry.
- To deploy the website locally, you would need to install graphviz to generate SVG files for dot files and juvix to render the Juvix code examples.
Install the required packages (preferably in the virtual environment) using Poetry:
```
poetry install
```

Building and serving the website¶

To generate the website in the site/ directory, run:
```
poetry run mkdocs build
```
To serve the website locally, run the following command:
```
poetry run mkdocs serve
```
Take into account that this web server will automatically reload the website when you make any changes to the files, and it is not especially fast.

Development shell with Nix¶

Install Nix: https://nixos.org/download/
Enable Nix Flakes: https://nixos.wiki/wiki/flakes
Enter development shell:
```
nix develop
```