Contributing

This guide helps you contribute to the Engineering Handbook using Material for MkDocs.

Installation

Clone the repository:

git clone https://github.com/futuredapp/Engineering-Handbook.git
cd Engineering-Handbook

Create a Virtual Environment:
```
python3 -m venv myenv
```
Activate the Virtual Environment:
```
source myenv/bin/activate
```
Install the required packages:
```
pip install mkdocs-material
pip install mkdocs-glightbox
```
Note

The mkdocs-material and plugin dependencies must be installed in the same Python environment.
Installing mkdocs-material from Homebrew and other plugins (mkdocs-glightbox) using pip might not work for you if you use pyenv or similar environment management tools.
When you're done, you can deactivate the environment with:
```
deactivate
```

Local Development

Activate the Virtual Environment:
```
source myenv/bin/activate
```
Run the following command from the repository root to start a local development server with live-reloading:
```
mkdocs serve
```
The documentation will be available at http://127.0.0.1:8000/Engineering-Handbook/.
When you're done, you can deactivate the environment with:
```
deactivate
```

Editing Guidelines

Making Changes

Create a new branch from main
Make your changes
Open a pull request to the Engineering Handbook repository
Get at least one approval before merging
After merging, the GitHub Action Pages workflow will automatically publish the updated documentation

Diagrams

Some diagrams are created using Excalidraw. When exporting images, ensure following:

Embed scene into exported image, or commit source .excalidraw file to the repository so it can be edited later by someone else.
Respect light and dark themes - export 2 images for light and dark backgrounds. Use the #only-light and #only-dark suffixes to specify which theme the image is for. See Light and dark mode for more details.
Use the data-gallery attribute to group images into a light gallery. For example, data-gallery="light" for light mode images and data-gallery="dark" for dark mode images. This ensures that lightbox will not display dark mode images in light mode and vice versa.
Related issue: blueswen/mkdocs-glightbox/issues/26

Full example of diagram with transparent background in light and dark variant and lightbox support:

![](../Resources/architecture/arch_kmp_light.png#only-light){data-gallery="light"}
![](../Resources/architecture/arch_kmp_dark.png#only-dark){data-gallery="dark"}

Markdown Syntax

Material for MkDocs uses standard Markdown with some additional features

Admonitions:

!!! note "Title"
    Content of the note

Edit the mkdocs.yml file to adjust the navigation structure.

Adding New Pages

Create a new Markdown file in the appropriate directory
Add the page to navigation in mkdocs.yml if needed

Project Structure

mkdocs.yml              # Configuration file
docs/
    index.md            # Documentation homepage
    editors.md          # Editors manual
    Teams/              # Teams space
        Team name/
            ...         # Pages
            Resources/  # Images, Diagrams, etc.

Troubleshooting

For more detailed information, refer to the Material for MkDocs documentation.