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

Question

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

However, despite the successful completion of the project in the "Reading Documents" section, the documentation retains the standard readthedocs theme. When I run it locally (using mkdocs serve ), it looks right with the United theme.

Is there another line of code that I have to configure somewhere? Requirements file that I should add? How can I make the external theme display correctly in ReadtheDocs ... or really, can I use external themes for readthedocs.org?

Note. I asked MkDocs users, and they said that this is a ReadTheDocs limitation, so if something is done, it looks like it will be a ReadTheDocs related solution. Otherwise, I may have to go to GitHub pages or something similar.

Answer 1

I took a look at the ReadtheDocs source code and it seems like they are actually overriding the configuration of the settings and creating their own template. As I understand it, they do this because they inject JavaScript and ReadtheDocs-specific navigation elements into your pages and, using a well-known theme, they can be sure that the injections are completed correctly. However, there should be no technical reason why you cannot use the same HTML as the readthedocs theme, but possibly different CSS, to change the appearance of the pages. Its just that ReadtheDocs doesn't seem to explicitly support this.

However, I noticed that the template override only happens if 'theme_dir' not in user_config and self.use_theme . This gives you two possible ways to avoid overriding. Just keep in mind that there is no guarantee that the injected material will work correctly, so be careful.

• theme_dir is a parameter of Mkdocs. Instead of installing the MkDocs theme as a separate Python library, you can copy the theme files to the directory next to docs_dir and then specify the theme_dir parameter for it. Just set theme: null so that MkDocs uses only theme_dir .

  Perhaps, as a less aggressive approach, you can install theme: readthedocs , and then use theme_dir only to provide your own CSS files that will override / replace CSS provided by the readthedocs built-in theme. This should be less hostile for ReadtheDocs injections and you will like it. However, this may require more work, since you are limited to the HTML theme of an existing theme and you will need to create your own CSS (without using an already built theme).

  In this case, you can install theme any theme you want, and then point theme_dir to an empty directory. It would seem that ReadtheDocs only verifies that theme_dir set, and anyway, that it actually exists in the directory.

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

  Aside, the MkdDocs documentation on how this all works (the interaction between the theme and theme_dir ) is currently very lacking. However, some recent additions will come alive with the release of the next version of MkDocs (0.16).

• use_theme seems to be specific to readthedocs and hardcoded internally. I assume this will not be excessive for the user. A deeper examination of the code will be needed to determine which options, if any, provide.