6

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

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

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

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

4

1 回答 1

4

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

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

  1. theme_dir是 Mkdocs设置。您可以将主题文件复制到旁边的目录中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。

    theme顺便说一句，关于这一切如何工作（和设置之间的交互）的 MkdDocs 文档theme_dir现在严重缺乏。然而，当下一版本的 MkDocs (0.16) 发布时，一些最近添加的内容将生效。

  2. use_theme似乎特定于 readthedocs 和内部硬编码。我的猜测是这不会被用户覆盖。需要对代码进行更深入的调查，以确定它提供了哪些选项（如果有的话）。

于 2016-06-22T14:00:57.547 回答