在 ReadTheDocs 托管的 Mkdocs 中使用额外的 CSS 文件

Question

我编写了一些自定义 CSS，希望将其包含在 ReadTheDocs 托管的 Mkdocs 站点中。它不起作用，因为 RTD 不提供 CSS 文件。

我有一个要求 RTD 使用 Mkdocs 的 .readthedocs.yml 文件：

version: 2
mkdocs:
  configuration: .mkdocs.yml

我的.mkdocs.yml 文件引用了我正在使用自定义 CSS 文件这一事实：

docs_dir: my-docs-directory
theme:
  name: 'material'
extra_css:
  - '.mkdocs.material.css'

ReadTheDocs 报告说文档构建良好，但是当我加载它们时，自定义 CSS 不起作用。如果我打开浏览器控制台，我会看到此错误：

拒绝应用来自 'https://private-site.readthedocs-hosted.com/en/latest/.mkdocs.material.css' 的样式，因为它的 MIME 类型 ('text/html') 不是受支持的样式表 MIME 类型，并且启用了严格的 MIME 检查。

如果我在其自己的选项卡中打开 CSS 文件 URL，我会看到“404 - 未找到”页面。

我尝试将 CSS 文件包含在根目录（.readthedocs.yml 和 .mkdocs.yml 所在的位置）和我的 docs 目录（my-docs-directory）中，但都不起作用。

我认为我需要 RTD 以某种方式知道将 CSS 文件作为静态文件提供，但我能找到的所有关于此的指南都特定于 Sphinx。

请帮忙！谢谢！

Answer 1

我认为这个问题是由于.mkdocs.material.css 开头的点造成的。看起来 MkDocs（mkdocs build，我使用 MkDocs v1.0）不会将隐藏文件（开头的点表示 Unix 系统上的隐藏文件）复制到输出目录。我认为如果您将文件重命名为 mkdocs.material.css 而不带前导点并更新您的 mkdocs.yml 中的引用，它应该可以工作。

您在阅读文档 (Refused to apply style ...) 中看到的更神秘的错误消息是因为 CSS 文件的链接标记 (<link>) 仍在构建输出中生成，但 MkDocs 并未实际复制 CSS 文件因为它被隐藏了。结果它给出了 404。Read the Docs 发送一个标题，告诉浏览器进行严格的 MIME 检查，这是处理用户上传文件时的一项重要安全措施。因为有一个指向 CSS 文件的链接，但响应是带有 HTML 的 404，所以浏览器会拒绝该样式。