Dev

This document provides notes for developers working on this project.

This project uses a custom version of the mkdocs-material theme. The customizations are located in the material/ directory.

To override a theme file (e.g., a partial like header.html or alternate.html), you need to:

Find the original file: The original theme files are located inside the Docker container at /usr/local/lib/python3.11/site-packages/material/templates/. You can explore the container's file system by running:
```
docker-compose run --rm epragma_docs ls -R /usr/local/lib/python3.11/site-packages/material
```
(Note: this requires temporarily changing the entrypoint in docker-compose.yaml to ls and the command to -R /usr/local/lib/python3.11/site-packages/material)
Copy the original file to the overrides directory: Once you have the path to the original file, you can copy its content to the material/overrides/ directory, preserving the same directory structure. For example, to override partials/header.html, you would copy its content to material/overrides/partials/header.html.
Modify the copied file: You can now modify the copied file in material/overrides/ to apply your customizations.

To override an icon used in the theme:

Create SVG files: Create your custom SVG icons.
Place the SVG files in the .icons directory: Place your custom SVG files in the material/overrides/.icons/ directory. If this directory doesn't exist, you need to create it.
Update mkdocs.yml: In mkdocs.yml, find the theme.icon section and update the path to your custom icon. For example, to use a custom link.svg icon, you would change:
```
theme:
  icon:
    alternate: material/link
```
to:
```
theme:
  icon:
    alternate: .icons/link
```

To run the site locally for development, you can use the following command:

docker-compose up

The site will be available at http://localhost:8500.

Remember that after making changes to the theme files, you might need to rebuild the Docker image to see the changes. You can do this by running:

docker-compose up --build