How to override templates

[ben519]

Recently solved a problem by overriding a template. Thought I'd document my steps as a mini tutorial for others.

Problem

I plan on having a lot of top-level sections in my nav like

theme:
  name: material
  features:
    - toc.integrate
    - navigation.tabs 

nav:
  - Home: index.md
  - Contributors: contributors.md
  - Super Awesome Course 1:
    - courses/course1/index.md
    - Section 1:
      - courses/course1/section1/example1.md
    - Section 2:
      - courses/course1/section2/example2.md
      - courses/course1/section2/example3.md
  - Super Awesome Course 2: course2.md
  - Super Awesome Course 3: course3.md
  - Super Awesome Course 4: course4.md
  - Super Awesome Course 5: course5.md
  - Super Awesome Course 6: course6.md

The problem is, this creates a very messy header..

So, I'd like to exclude Super Awesome Course 1, Super Awesome Course 2, ... from the header. (They'll still be accessible via links on my home page.) How can I exclude these links from the header?

Solution

A good solution is to tweak the html template to exclude them. The final html for the site is generated from a spider web of templates that reference variables and other templates. The whole thing is based on a templating engine called Jinja.

Which Template?

First question is which template do I override?.

To answer this, inspect the header in chrome developer tools and look for a unique element identifier for tabs..

"md-tabs__list" looks pretty identifying. Let's search for it in the repo..

src/partials/tabs.html looks like what we want.

How to override?

The code here is quite simple.

<!-- Navigation tabs -->
<nav
  class="md-tabs"
  aria-label="{{ lang.t('tabs.title') }}"
  data-md-component="tabs"
>
  <div class="md-tabs__inner md-grid">
    <ul class="md-tabs__list">
      {% for nav_item in nav %}
        {% include "partials/tabs-item.html" %}
      {% endfor %}
    </ul>
  </div>
</nav>

Our goal is to modify it like this, so that only Home and Contributors show in the header.

<!-- Navigation tabs -->
<nav
  class="md-tabs"
  aria-label="{{ lang.t('tabs.title') }}"
  data-md-component="tabs"
>
  <div class="md-tabs__inner md-grid">
    <ul class="md-tabs__list">
      {% for nav_item in nav %}

        {% if nav_item in ['Home', 'Contributors'] %}
            {% include "partials/tabs-item.html" %}
        {% endif %}

      {% endfor %}
    </ul>
  </div>
</nav>

Here's how we do it (following the instructions here).

1. Copy src/partials/tabs.html to overrides/partials/tabs.html where overrides/ is a sibling directory of docs/
2. Tell MkDocs you want it to use your overrides/ directory by setting the custom_dir attribute in mkdocs.yml like

theme:
  name: material
  custom_dir: overrides

3. Modify the code in tabs.html to make use of the if statement (as shown above ^).
4. mkdocs serve as usual to build the site..

This doesn't work.

How to debug?

To see what went wrong, change tabs.html like so

<!-- Hack: unset variable, as we're using it recursively in tabs-item.html -->
{% set class = "" %}

<!-- Navigation tabs -->
<nav
  class="md-tabs"
  aria-label="{{ lang.t('tabs.title') }}"
  data-md-component="tabs"
>
  <div class="md-tabs__inner md-grid">
    <ul class="md-tabs__list">
      {% for nav_item in nav %}

        <h1>{{nav_item}}</h1>

      {% endfor %}
    </ul>
  </div>
</nav>

and re-serve the site.

As you can see, nav_item is an object. To get the title, we need to use nav_item.title. Again, we change our overridden tabs.html file as

<!-- Hack: unset variable, as we're using it recursively in tabs-item.html -->
{% set class = "" %}

<!-- Navigation tabs -->
<nav
  class="md-tabs"
  aria-label="{{ lang.t('tabs.title') }}"
  data-md-component="tabs"
>
  <div class="md-tabs__inner md-grid">
    <ul class="md-tabs__list">
      {% for nav_item in nav %}

        {% if nav_item.title in ['Home', 'Contributors'] %}
            {% include "partials/tabs-item.html" %}
        {% endif %}

      {% endfor %}
    </ul>
  </div>
</nav>

Alas, it works!

How to use a variable

One more thing.. I don't want to tweak tags.html every time I want to include or exclude a page. It'd be nicer if I could create a variable in mkdocs.yml like include_headers = ['Home', 'Contributors'] which I could reference in the tabs.html template.

To set this up, create the header_items variable as an attribute below extra. Like this

extra:
  generator: false
  header_items:
    - Home
    - Contributors

Then in tabs.html change

{% if nav_item.title in ['Home', 'Contributors'] %}

to

{% if nav_item.title in config.extra.header_items %}

[squidfunk]

Thanks! Great tutorial!

[SPyofgame200]

While override is recommended, I found a solution for certain things that don't have their partials HTML parts

By using js injection in extra_Js

const logoContainer = document.querySelector('.md-header__button.md-logo');
const logoImage = logoContainer.querySelector('img');
const iconifyStructure = `
<div class="iconify">
 <div class="iconify_wrapper">
    <div class="iconify_box">
      <div class="iconify_box-inner">
        <div class="iconify_bar"></div>
        <div class="iconify_bar"></div>
        <div class="iconify_bar"></div>
        <div class="iconify_bar"></div>
        <img class="iconify_img" alt="${logoImage.alt}" src="${logoImage.src}">
      </div>
    </div>
 </div>
</div>
`;
logoContainer.innerHTML = iconifyStructure;

[kamilkrzyskow]

GitHub search isn't the best also you've searched including the dots which aren't in the HTML

mkdocs-material/src/templates/partials/header.html

Line 42 in 4eb1a43

class="md-header__button md-logo"

mkdocs-material/src/templates/partials/logo.html

Line 25 in 4eb1a43

<img src="{{ config.theme.logo | url }}" alt="logo" />

[W1ndys]

Very good tutorial, it increased my knowledge