Can I use external themes with MkDocs on readthedocs.org?

Question

I switched from the included ReadtheDocs theme to the bootswatch United theme for my project. I did a pip install mkdocs-bootswatch for this theme, and changed theme: readthedocs to theme: united in my mkdocs.yml file.

However, although the project builds successfully in Read the Docs, the documentation retains the standard readthedocs theme. When I run it locally (using mkdocs serve), it appears correctly with the United theme.

Is there another line of code I should be tweaking somewhere? A requirements file I should add? How can I get the external theme to properly appear in the ReadtheDocs... or indeed, can I even use external themes on readthedocs.org?

Note: I did ask the MkDocs folks and they said it was a ReadTheDocs limitation, so if there is anything to be done, it seems like it will be a ReadTheDocs-related solution. Otherwise, I may have to switch to GitHub pages or something similar.

Answer 1

I took a look at ReadtheDocs source code and it appears that they actually override your settings config and force their own template. As I understand it, they do this because they inject JavaScript and navigation stuff specific to ReadtheDocs into your pages and by using a known theme, they can be sure the injections are done correctly. That said, there shouldn't be any technical reason why you can't use the same HTML as the readthedocs theme but perhaps different CSS to alter the look/styling of the pages. Its just that ReadtheDocs appears to not explicitly support this.

That said, I did notice that the template override only happens if 'theme_dir' not in user_config and self.use_theme. That gives you two possible paths to avoid the override. Just be aware that there will be no guarantee that the injected stuff will work correctly so tread carefully.

1. theme_dir is a Mkdocs setting. Rather than installing a MkDocs theme as a separate Python library, you could copy the theme files into a directory next to the docs_dir and then point the theme_dir setting to it. Just be sure to set theme: null so that MkDocs only uses the theme_dir.

   Perhaps as a less aggressive approach, you could set theme: readthedocs, and then use theme_dir to only supply your own CSS files which would override/replace the CSS supplied by the built-in readthedocs theme. This should be less hostile to ReadtheDocs injections and give you a look you like. However, this may require more work to get right as you are restricted to the HTML of the existing theme and will need to author your own CSS (no using an already built theme).

   For that matter, you could set theme to whatever theme you want and then point theme_dir to an empty directory. It would appear that ReadtheDocs only checks that theme_dir is set, and doesn't care what actually exists in the directory.

   Note: I have not tested any of these suggestions and cannot be certain they will work. YMMV.

   As an aside, the MkdDocs documentation about how this all works (interaction between the theme and theme_dir settings) is severely lacking right now. However some recent additions will become live when the next version of MkDocs (0.16) is released.

2. use_theme appears to be specific to readthedocs and hardcoded internally. My guess is that this will not be overridable by a user. A deeper investigation of the code would be needed to determine what, if any, options this provides.