我可以在readthedocs.org上的MkDocs中使用外部主题吗？

Question

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

然而，尽管项目在Read the Docs中成功构建，文档仍然保留了标准的readthedocs主题。当我在本地运行它(使用< code>mkdocs serve)时，它正确地显示了United主题。

是否还有其他代码行我应该在某处调整？我应该添加的需求文件？如何使外部主题正确地显示在ReadtheDocs中……或者，我甚至可以在ReadtheDocs.org上使用外部主题？

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

Answer 1

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

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

>

theme_dir是一个Mkdocs设置。您可以将主题文件复制到＜code＞docs_dir。

也许作为一种不太激进的方法，您可以设置< code>theme: readthedocs，然后使用< code>theme_dir来只提供您自己的CSS文件，这些文件将覆盖/替换内置readthedocs主题提供的CSS。这样应该对ReadtheDocs注射的敌意小一点，给你一个你喜欢的样子。然而，这可能需要更多的工作来做好，因为你被限制在现有主题的HTML，并需要创作自己的CSS(不使用已经建立的主题)。

为此，您可以将< code>theme设置为您想要的任何主题，然后将< code>theme_dir指向一个空目录。看起来ReadtheDocs只检查了< code>theme_dir的设置，并不关心目录中实际存在什么。

注意：我没有测试过这些建议中的任何一个，也不能确定它们是否有效。新浪网.

另外，关于这一切是如何工作的MkdDocs文档(在< code>theme和< code>theme_dir设置之间的交互)现在严重缺乏。然而，当MkDocs的下一个版本(0.16)发布时，一些最新的添加将会生效。

＜code＞use_theme＜/code＞似乎专门用于读取文档，并在内部进行硬编码。我猜这不会被用户覆盖。需要对代码进行更深入的调查，以确定这提供了哪些选项（如果有的话）。