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

Question

我写了一些自定义内容 CSS 我想加入由 ReadTheDocs 托管的 Mkdocs 站点。它不起作用，因为 RTD 不提供 CSS 文件。

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

version: 2
mkdocs:
  configuration: .mkdocs.yml

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

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

ReadTheDocs 报告文档构建良好，但当我加载它们时，自定义 CSS 无效。如果我打开浏览器控制台，我会看到这个错误：

Refused to apply style from 'https://private-site.readthedocs-hosted.com/en/latest/.mkdocs.material.css' because its MIME type ('text/html') is not a supported stylesheet MIME type, and strict MIME checking is enabled.

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

我尝试将 CSS 文件包含在根目录（.readthedocs.yml 和 .mkdocs.yml 所在的位置）和我的文档目录 (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 标记 (<link>) 仍然生成在构建输出中，但 MkDocs 实际上并没有复制 CSS 文件，因为它是隐藏的。结果它给出 404。阅读文档发送 header 告诉浏览器进行严格的 MIME 检查，这是处理用户上传文件时的一项重要安全措施。因为有 link 到 CSS 文件，但响应是带有 HTML 的 404，浏览器拒绝该样式。

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

Using extra CSS file with Mkdocs hosted by ReadTheDocs

read-the-docs

mkdocs