我可以在 readthedocs.org 上将外部主题与 MkDocs 一起使用吗？
Can I use external themes with MkDocs on readthedocs.org?
我的项目从附带的 ReadtheDocs 主题切换到 bootswatch United 主题。我为这个主题做了一个 pip install mkdocs-bootswatch，并在我的 mkdocs.yml 文件中将 theme: readthedocs 更改为 theme: united。
然而，尽管项目在阅读文档中构建成功，但文档保留了标准的 readthedocs 主题。当我在本地 运行 时（使用 mkdocs serve），它会正确显示 United 主题。
我应该在某处调整另一行代码吗？我应该添加一个需求文件？我怎样才能让外部主题正确出现在 ReadtheDocs 中……或者实际上，我什至可以在 readthedocs.org 上使用外部主题吗？
注意：我确实问过 MkDocs 的人，他们说这是 ReadTheDocs 的限制，所以如果有什么需要做的，看起来它将是一个 ReadTheDocs 相关的解决方案。否则，我可能不得不切换到 GitHub 页面或类似内容。
我查看了 ReadtheDocs source code，他们似乎实际上覆盖了您的设置配置并强制使用他们自己的模板。据我了解，他们这样做是因为他们将 JavaScript 和特定于 ReadtheDocs 的导航内容注入到您的页面中，并且通过使用已知主题，他们可以确保注入正确完成。也就是说，不应该有任何技术原因导致您不能使用与 readthedocs 主题相同的 HTML 但可能使用不同的 CSS 来更改页面的 look/styling。只是 ReadtheDocs 似乎没有明确支持这一点。
也就是说，我确实注意到模板覆盖只会发生 if 'theme_dir' not in user_config and self.use_theme。这为您提供了避免覆盖的两条可能路径。请注意，无法保证注入的内容会正常工作，因此请谨慎行事。
theme_dir 是一个 Mkdocs setting。与其将 MkDocs 主题安装为单独的 Python 库，不如将主题文件复制到 docs_dir 旁边的目录中，然后将 theme_dir 设置指向它。请务必设置 theme: null 以便 MkDocs 仅使用 theme_dir.
也许作为一种不那么激进的方法，您可以设置 theme: readthedocs，然后使用 theme_dir 来仅提供您自己的 CSS 文件，这将 override/replace CSS 由内置的 readthedocs 主题提供。这应该对 ReadtheDocs 注入没有那么大的敌意，并给你一个你喜欢的外观。但是，这可能需要更多的工作才能正确完成，因为您受限于现有主题的 HTML，并且需要创作您自己的 CSS（不使用已经构建的主题）。
就此而言，您可以将 theme 设置为您想要的任何主题，然后将 theme_dir 指向一个空目录。 ReadtheDocs 似乎只检查是否设置了 theme_dir，并不关心目录中实际存在的内容。
注意：我没有测试过这些建议中的任何一个，不能确定它们是否有效。 YMMV.
顺便说一句，目前严重缺乏关于这一切如何工作的 MkdDocs 文档（theme 和 theme_dir 设置之间的交互）。然而，一些最近的 additions 将在下一个版本的 MkDocs (0.16) 发布时上线。
use_theme 似乎特定于 readthedocs 和 hardcoded 内部。我的猜测是这不会被用户覆盖。需要对代码进行更深入的研究以确定它提供了哪些选项（如果有的话）。
我的项目从附带的 ReadtheDocs 主题切换到 bootswatch United 主题。我为这个主题做了一个 pip install mkdocs-bootswatch，并在我的 mkdocs.yml 文件中将 theme: readthedocs 更改为 theme: united。
然而，尽管项目在阅读文档中构建成功，但文档保留了标准的 readthedocs 主题。当我在本地 运行 时（使用 mkdocs serve），它会正确显示 United 主题。
我应该在某处调整另一行代码吗？我应该添加一个需求文件？我怎样才能让外部主题正确出现在 ReadtheDocs 中……或者实际上，我什至可以在 readthedocs.org 上使用外部主题吗？
注意：我确实问过 MkDocs 的人，他们说这是 ReadTheDocs 的限制，所以如果有什么需要做的，看起来它将是一个 ReadTheDocs 相关的解决方案。否则，我可能不得不切换到 GitHub 页面或类似内容。
我查看了 ReadtheDocs source code，他们似乎实际上覆盖了您的设置配置并强制使用他们自己的模板。据我了解，他们这样做是因为他们将 JavaScript 和特定于 ReadtheDocs 的导航内容注入到您的页面中，并且通过使用已知主题，他们可以确保注入正确完成。也就是说，不应该有任何技术原因导致您不能使用与 readthedocs 主题相同的 HTML 但可能使用不同的 CSS 来更改页面的 look/styling。只是 ReadtheDocs 似乎没有明确支持这一点。
也就是说，我确实注意到模板覆盖只会发生 if 'theme_dir' not in user_config and self.use_theme。这为您提供了避免覆盖的两条可能路径。请注意，无法保证注入的内容会正常工作，因此请谨慎行事。
theme_dir是一个 Mkdocs setting。与其将 MkDocs 主题安装为单独的 Python 库，不如将主题文件复制到docs_dir旁边的目录中，然后将theme_dir设置指向它。请务必设置theme: null以便 MkDocs 仅使用theme_dir.也许作为一种不那么激进的方法，您可以设置
theme: readthedocs，然后使用theme_dir来仅提供您自己的 CSS 文件，这将 override/replace CSS 由内置的 readthedocs 主题提供。这应该对 ReadtheDocs 注入没有那么大的敌意，并给你一个你喜欢的外观。但是，这可能需要更多的工作才能正确完成，因为您受限于现有主题的 HTML，并且需要创作您自己的 CSS（不使用已经构建的主题）。就此而言，您可以将
theme设置为您想要的任何主题，然后将theme_dir指向一个空目录。 ReadtheDocs 似乎只检查是否设置了theme_dir，并不关心目录中实际存在的内容。注意：我没有测试过这些建议中的任何一个，不能确定它们是否有效。 YMMV.
顺便说一句，目前严重缺乏关于这一切如何工作的 MkdDocs 文档（
theme和theme_dir设置之间的交互）。然而，一些最近的 additions 将在下一个版本的 MkDocs (0.16) 发布时上线。use_theme似乎特定于 readthedocs 和 hardcoded 内部。我的猜测是这不会被用户覆盖。需要对代码进行更深入的研究以确定它提供了哪些选项（如果有的话）。