Extending the Material theme

[kattni]

Hello!

I am working on getting a custom header going on my documentation. The first thing I tried was getting a custom CSS file applied. My docs_dir is docs/en for translation reasons, so the extra_css key in mkdocs.yml doesn't work. I'm instead using the custom_dir: overrides feature on the Material theme, which is ultimately what I need anyway. It's definitely seeing it, because it renders any HTML I add (albeit emptily for now). However, it's not seeing the CSS by default. So I created a main.html file, and used {% block styles %} to enable the CSS file. It's definitely seeing it now, but it seems to have lost all other stylesheets attached to Material in the process. I feel like I'm missing something obvious here, but I'm stumped at this point.

Any assistance is appreciated.
Thanks!

[kamilkrzyskow]

Hello @kattni,
the styles block contains all of the styles, so you have to remember to add a {{ super() }} call to load the initial value and then add your own. Or use extrahead, which is empty by default, so it only contains the new values.

mkdocs-material/material/templates/base.html

Lines 46 to 53 in 08fd869

	{% block styles %}
	<link rel="stylesheet" href="{{ 'assets/stylesheets/main.7e37652d.min.css' | url }}">
	{% if config.theme.palette %}
	{% set palette = config.theme.palette %}
	<link rel="stylesheet" href="{{ 'assets/stylesheets/palette.06af60db.min.css' | url }}">
	{% endif %}
	{% include "partials/icons.html" %}
	{% endblock %}

As a side note don't forget to use the url filter to properly manage relative paths for your custom file.

Reference:

• https://squidfunk.github.io/mkdocs-material/customization/#overriding-blocks
  Scroll a bit for an example with {{ super() }}
• https://squidfunk.github.io/mkdocs-material/reference/#on-a-single-page
  Shows extrahead in use

[kattni]

I saw {{ super() }} somewhere in my readings, and completely forgot about it. I didn't know about extrahead though.

Thank you so much!