Using extra CSS file with Mkdocs hosted by ReadTheDocs

Question

I have written some custom CSS I would like to be included in a Mkdocs site hosted by ReadTheDocs. It is not working because RTD isn't serving the CSS file.

I have a .readthedocs.yml file that asks RTD to use Mkdocs:

version: 2
mkdocs:
  configuration: .mkdocs.yml

My .mkdocs.yml file references the fact that I'm using a custom CSS file:

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

ReadTheDocs reports that the docs built fine, but when I load them the custom CSS isn't in effect. If I open the browser Console I see this error:

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.

If I open the CSS file URL in its own tab I see a "404 - Not found" page.

I tried including the CSS file in both root (where .readthedocs.yml and .mkdocs.yml live) and in my docs directory (my-docs-directory), but neither work.

I think I need RTD to somehow know to serve the CSS file up as a static file, but all guidelines I could find about this are specific to Sphinx.

Please help! Thanks!

Answer 1

I believe this issue is due to the dot at the beginning of .mkdocs.material.css. It looks like MkDocs (mkdocs build, I used MkDocs v1.0) won't copy hidden files -- the dot at the beginning denotes a hidden file on Unix systems -- to the output directory. I think if you rename the file to be mkdocs.material.css without the leading dot and update the reference in your mkdocs.yml, it should work.

The more cryptic error message you see on Read the Docs (Refused to apply style ...) is because the link tag (<link>) to the CSS file is still generated in the build output but MkDocs didn't actually copy the CSS file because it was hidden. As a result it gives a 404. Read the Docs sends a header telling browsers to do strict MIME checking which is an important security measure when handling user uploaded files. Because there's a link to a CSS file but the response is a 404 with HTML, the browser rejects the style.