Including extra.css with mkdocs

Question

The documentation of mkdocs describes a way to include some extra css customization without overriding an entire file as you would do with a custom_theme directory.

Consider the following example:

• mkdocs.yml:

site_name: MWE
nav:
- 'Home': index.md
theme:
  name: mkdocs
  extra_css: [extra.css]

• index.md

# Home
## Lorem ipsum
Lorem ipsum dolor sit amet.

• extra.css:

h1 {
  color: red;
}

With the following file tree:

$ tree .
.
├── docs
│   ├── extra.css
│   └── index.md
└── mkdocs.yml

Then running mkdocs serve (mkdocs v1.4.2, Python 3.9) I would expect to yield a website with a red header. Which I don't. I get:

I've tried placing extra.css in other places, using mkdocs straight from the master branch, using the readthedocs theme instead, changing other stuff in the css to see if that changes, different browsers and probably more that I don't remember to list. But at no time I've seen any changes on the actual webpage. Normally I would have started to expect that it was a bug with mkdocs but considering that mkdocs is quite well used and this is what I gather to be the recommended way to customize your webpage, I find it more probable that there is something that I'm still missing.

What am I missing to get mkdocs to pick up the extra.css file properly?

Update: extra.css working as expected when manually added

I've noticed that if I manually include extra.css in the markdown files

<link rel="stylesheet" href="extra.css" />
# Home
## Lorem ipsum
Lorem ipsum dolor sit amet.

it is picked and the header "Home" turns red. So there is nothing wrong with the extra.css file at least.

Update 2: Problem with populating extra_css variable

I've been able to isolate the problem a bit further. By using the following mkdocs.yml:

site_name: MWE
nav:
- 'Home': index.md
theme:
  name: mkdocs
  extra_css: [extra.css]
  custom_dir: custom_theme/

and adding the file custom_theme/main.html with content:

{% extends "base.html" %}
{% block styles %}
    {{ super() }}
    {% if extra_css|length == 0 %}<link href="{{ 'extra.css'|url }}" rel="stylesheet">{% endif %}
{% endblock %}

I could see that the variables extra_css, config.extra_css and config['extra_css'] all had length 0 (by seeing if extra.css was picked up or not when I varied variable and check for == 0 or > 0). In base.html it is the variable extra_css that is used.

Answer 1

The solution was as simple and as I figured it should have been for the start. There were an extra indentation in my mkdocs.yml. It is extra_css not theme.extra_css, as such the correct mkdocs.yml is:

site_name: MWE
nav:
- 'Home': index.md
theme:
  name: mkdocs
extra_css: [extra.css]

note the new indentation.