我可以在 readthedocs.org 上将外部主题与 MkDocs 一起使用吗？答案

【问题标题】：Can I use external themes with MkDocs on readthedocs.org?我可以在 readthedocs.org 上将外部主题与 MkDocs 一起使用吗？
【发布时间】：2016-10-23 12:04:39
【问题描述】：

我从包含的 ReadtheDocs 主题切换到我的项目的 bootswatch United 主题。我为这个主题做了一个pip install mkdocs-bootswatch，并在我的mkdocs.yml 文件中将theme: readthedocs 更改为theme: united。

但是，尽管项目在 Read the Docs 中构建成功，但文档保留了标准的 readthedocs 主题。当我在本地运行它（使用mkdocs serve）时，它以 United 主题正确显示。

我应该在某处调整另一行代码吗？我应该添加一个需求文件？我怎样才能让外部主题正确出现在 ReadtheDocs 中……或者实际上，我什至可以在 readthedocs.org 上使用外部主题吗？

注意：我确实问过 MkDocs 的人，他们说这是 ReadTheDocs 的限制，所以如果有什么需要做的，它似乎是一个与 ReadTheDocs 相关的解决方案。否则，我可能不得不切换到 GitHub 页面或类似的东西。

【问题讨论】：

标签： read-the-docs mkdocs

【解决方案1】：

我查看了 ReadtheDocs source code，看来它们实际上覆盖了您的设置配置并强制使用自己的模板。据我了解，他们这样做是因为他们将特定于 ReadtheDocs 的 JavaScript 和导航内容注入到您的页面中，并且通过使用已知主题，他们可以确保注入正确完成。也就是说，不应该有任何技术原因导致您不能使用与 readthedocs 主题相同的 HTML，但可能使用不同的 CSS 来改变页面的外观/样式。只是 ReadtheDocs 似乎没有明确支持这一点。

也就是说，我确实注意到模板覆盖只发生if 'theme_dir' not in user_config and self.use_theme。这为您提供了两种可能的路径来避免覆盖。请注意，无法保证注入的东西会正常工作，因此请小心行事。

theme_dir 是一个 Mkdocs setting。您可以将主题文件复制到 docs_dir 旁边的目录中，然后将 theme_dir 设置指向它，而不是将 MkDocs 主题安装为单独的 Python 库。请务必设置theme: null，以便 MkDocs 仅使用 theme_dir。

也许作为一种不太激进的方法，您可以设置theme: readthedocs，然后使用theme_dir 仅提供您自己的CSS 文件，这些文件将覆盖/替换内置readthedocs 主题提供的CSS。这应该对 ReadtheDocs 注入不那么敌对，并给你一个你喜欢的样子。但是，这可能需要更多的工作才能正确完成，因为您受限于现有主题的 HTML，并且需要编写自己的 CSS（不使用已构建的主题）。

就此而言，您可以将theme 设置为您想要的任何主题，然后将theme_dir 指向一个空目录。 ReadtheDocs 似乎只检查 theme_dir 是否已设置，并不关心目录中实际存在的内容。

注意：我没有测试过这些建议中的任何一个，并且不能确定它们是否会起作用。 YMMV。

顺便说一句，关于这一切如何工作的 MkdDocs 文档（theme 和 theme_dir 设置之间的交互）目前严重缺乏。然而，一些最近的additions 将在下一个版本的 MkDocs (0.16) 发布时生效。
use_theme 似乎特定于 readthedocs 和 hardcoded 内部。我的猜测是这不会被用户覆盖。需要对代码进行更深入的调查，以确定它提供了哪些选项（如果有的话）。

【讨论】：