In this post I’ll recount the steps I followed to create the ReadTheDocs Dropdown theme.
Goal: Provide collapsable menu support in a MkDocs theme.
Using their theming guide, I set up a theme repository with the ReadTheDocs theme from the mkdocs repo. At this point, the theme is just a copy of the existing ReadTheDocs theme.
The first step in adjusting a MkDocs theme is understanding what the MkDocs source does when it parses markdown.
To do this, I forked mkdocs and added debugging statements in a new
Using virtualenv, I setup a env with my modified version of mkdocs. First I switch the official mkdocs package with my
dev branch (currently commented out) in
requirements.txt. Then I create and activate my environment with the following commands:
virtualenv .env source .env/bin/activate pip install -r requirements.txt source .env/bin/activate
Now, when I run
mkdocs serve the first output message i see is my development indicator:
(.env) mkdocs-rtd-dropdown $ mkdocs serve INFO - Development Branch: cjsheets/mkdocs INFO - Building documentation...
Now I can add debug statements anywhere in the mkdocs build process to inspect how my theme is being applied.
Alternatively, I can point
requirements.txt to my local mkdocs repository and install using a local, development copy.
pip install -e /...path/mkdocs/