Overriding HTML templates

[MyNameIsNeXTSTEP]

Preconditions

Mkdocs has build in HMTL template blocks, particularly for table-of-contents (toc). I work with Mkdocs-material, so it uses inside base.html the toc template like this, which is declared here for example.

Right after that line of toc-item.html i want to insert my custom socials block:

{% include "partials/socials.html" %}

Problem

Mkdocs is made such a way, that it uses the class of nav block of secondary type(class), and also it is used for the nested secondary level navigation tab in another toc block (left sidebar).

These two different blocks with similar inner nav-secondary classes you can see here:

When i insert the custom block to toc.html right after md-nav__list it gets embedded in two places and ruins the layout.

Solutions used

• I tried to extend with {% extends "toc.html" %} default template layout and reconfigure classes for passing my template, didn't work
• I tried to copy all the base.html and disable/reconfigure special toc with different class, didn't work - whole page layout crashes.

Question

I want to insert my custom template after right side toc block, how can i determine this place specifically from templates or in another way ?

[MyNameIsNeXTSTEP]

Question is open yet

[kamilkrzyskow]

That's really a question for the Material for MkDocs discussion board, as the theme defines the HTML partials that are rendered into the final website.

But anyway, the toc.html partial is included in both the content of the page and in the navigation, because toc in the navigation is being shown when the page is in mobile / portrait mode.

https://github.com/squidfunk/mkdocs-material/blob/929fc39dbe67dd5a2044636c81028270679d9213/material/templates/base.html#L177
https://github.com/squidfunk/mkdocs-material/blob/929fc39dbe67dd5a2044636c81028270679d9213/material/templates/partials/nav-item.html#L124

So basically to focus on the toc in the content on the right side, you need to override the base.html, there are multiple approaches to that:

1. Create a main.html file and extend base.html file and extend the site_nav block, as explained per the documentation
   https://squidfunk.github.io/mkdocs-material/customization/#__codelineno-8-3
   https://github.com/squidfunk/mkdocs-material/blob/929fc39dbe67dd5a2044636c81028270679d9213/material/templates/base.html#L157-L182
   Issue is that you have to copy over the whole thing and only change a part of it, I guess this part:
   a.

   <div class="md-sidebar__inner">
      {% include "partials/toc.html" %}
      {% include "partials/socials.html" %}
   </div>

   or
   b.

   <div class="md-sidebar__inner">
      {% include "partials/custom-toc.html" %}
   </div>

   Where the first suggestion adds the socials after the nav containing the toc, and the second suggestion uses a custom toc.html partial to avoid duplicate socials.
   This approach as it requires some copy pasting, could also require some maintenance, depending on how the Material theme updates the sections you copied.
2. Dynamically override the base.html using a hook. How to dynamically override templates with hooks? squidfunk/mkdocs-material#5060
   I've changed the approach a bit from the one in the guide, and haven't had time to update it. Should still be useful.
   This approach would immediately notify you of incompatible changes after a Material theme update, but could require similar or even more maintenance in this case.
3. Accept that you will have the socials partial included 2 times.
4. Maintain a custom base.html. Overall the worst option, just wrote it down to make the other options look better.

[MyNameIsNeXTSTEP]

Thanx, seems like the working solution to me, haven't try it yet.
When test it, i will report the result here.