How to test mkdocs-material template changes locally?

[Rylon]

Hi there,

We are using Material for MkDocs to develop a documentation directory and it's excellent, but we found some accessibility issues with the generated HTML. We’d like to see if we can solve them, and contribute the fixes back.

Before we can do that we wanted to test the changes locally, but we’re struggling. What we tried was cloning mkdocs-material locally, editing the parts of the templates that needed changing, and then used pip to install it directly from the clone path (having removed the public version we got from PyPi).

When we tried to build our docs site again, we saw no changes in the generated HTML, so obviously we’ve done something wrong.

Would you be able to guide us on how to test these changes locally please?
Thanks for your help!

[squidfunk]

Thanks for asking and investigating the issues you found. Just follow the theme development process we explain in our documentation – it's the exact same approach we're using when working on the project. Make sure to make your changes in the src directory, since the material directory contains only generated files and is always re-generated during the build.

[Rylon]

Just posting this from below, to keep all the answers together. In the mkdocs project that will use the theme, you can test the changes like this: pip install -e ./path/to/your-mkdocs-material-clone

[Rylon]

Thanks, I'll give that a try. Having a quick read it's not immediately clear to me how the output from the mkdocs build at the end can then be used with a second repository that has mkdocs-material in the requirements.txt file? Do you have a recommended way of utilising the output?

[squidfunk]

I'm not sure what you mean. If you want to make changes to the code base of Material for MkDocs, the process I described is the way to go. You can test the changes live in another project by installing from a folder with:

pip install -e ./path/to/your-clone

Again, this is the exact process I'm using when testing changes or trying out reproductions.

[Rylon]

Aha yes that's the missing piece, thank you very much :)