For Editors

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

Installation

1. 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.

2. Clone the repository:

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

Local Development

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/.

Editing Guidelines

Making Changes

1. Create a new branch from main
2. Make your changes
3. Open a pull request to the Engineering Handbook repository
4. Get at least one approval before merging
5. 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
  

Editing Navigation

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

Adding New Pages

1. Create a new Markdown file in the appropriate directory
2. 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.