Is it possible to load custom sidebar HTML files natively without JavaScript?

[oliveira-mark]

Hello!

I'm working on customizing a documentation site and would like to know if it's possible to add custom HTML files to the sidebar natively, without using JavaScript.

Specifically, I need to insert four files or HTML code in the sidebar:

• On the left side: one at the top and one at the bottom.
• On the right side: one at the top and one at the bottom.

I have read the customization options in the documentation (Customization Guide), but I couldn’t find a way to achieve this without JavaScript.

Currently, I am using JavaScript to load these files dynamically:

• partials/sidebar-left-top.html
• partials/sidebar-left-bottom.html
• partials/sidebar-right-top.html
• partials/sidebar-right-bottom.html

Is there a way to load these files natively within MkDocs Material, without requiring JavaScript?

Thanks in advance! 😊

[kamilkrzyskow]

Hello @oliveira-mark,
depends a bit on your specific case, specifically, how do you target the place where it needs to be added?
Using customization and code block overrides you can add content directly above and blow the side bar:

• https://squidfunk.github.io/mkdocs-material/customization/#overriding-blocks

• mkdocs-material/src/templates/base.html

  Lines 294 to 334 in 0918657

  	<!-- Sidebars -->
  	{% block site_nav %}
  	<!-- Navigation -->
  	{% if nav %}
  	{% if page.meta and page.meta.hide %}
  	{% set hidden = "hidden" if "navigation" in page.meta.hide %}
  	{% endif %}
  	<div
  	class="md-sidebar md-sidebar--primary"
  	data-md-component="sidebar"
  	data-md-type="navigation"
  	{{ hidden }}
  	>
  	<div class="md-sidebar__scrollwrap">
  	<div class="md-sidebar__inner">
  	{% include "partials/nav.html" %}
  	</div>
  	</div>
  	</div>
  	{% endif %}
  	<!-- Table of contents -->
  	{% if "toc.integrate" not in features %}
  	{% if page.meta and page.meta.hide %}
  	{% set hidden = "hidden" if "toc" in page.meta.hide %}
  	{% endif %}
  	<div
  	class="md-sidebar md-sidebar--secondary"
  	data-md-component="sidebar"
  	data-md-type="toc"
  	{{ hidden }}
  	>
  	<div class="md-sidebar__scrollwrap">
  	<div class="md-sidebar__inner">
  	{% include "partials/toc.html" %}
  	</div>
  	</div>
  	</div>
  	{% endif %}
  	{% endblock %}

  
  The site_nav code block targets the side bars, and you can copy the contents from base.html and add your own spin on things.

If the above isn't specific enough to target your needed locations, there is also the option to dynamically inject logic into the templates with Python:

• How to dynamically override templates with hooks? #5060
  This method does modify the filesystem files/templates on-the-fly and restores them after the build, which was never optimal, but got the job done.

Some time ago, when working at Nype on the sap_icons plugin I stumbled upon a way to override the file loading directly at Jinja level. This could be used to improve the method above for dynamic hook overrides as there would be no need to modify the filesystem, however I never got around to refactoring the solution.

[oliveira-mark]

@kamilkrzyskow It worked! The base.html code you provided was exactly what I needed. I applied it to my main.html, and now I can customize the section I wanted.

Thank you so much for your help! It’s a simple solution, but without this reference, I wouldn’t have been able to do it. 🚀

[kamilkrzyskow]

Hey @oliveira-mark,
after helping out here I got another idea for validating block overrides, which can be useful to avoid falling behind when any updates are added to the theme.

You can look at the gist if you want;

• https://gist.github.com/kamilkrzyskow/2ea83bab91f790ccfa16f0e41f7ac2e0

Or example here: validation_super.zip

The hook calculates the hash of the rendered content, so it's necessary to limit the depth to limit the amount of HTML tags to compare to only include the ones from the block in the template file, so the depth could be increased to 3 in the example above, I set it to 2, so that you can see for yourself how it works.

The logic in the dynamic hook injection linked before was a bit different, because it would only fail when a placeholder for replacement could not be found, and here it generates a checksum hash for the rendered excerpt. The dynamic injection was more permissive of changes as it would work as long the placeholder was found, but here it will log a warning if there is any change in the rendered HTML tags. The content of the tags is skipped, so the detection is mostly limited to class/attribute modification etc.

[oliveira-mark]

Hi @kamilkrzyskow!

Thanks for sharing this! I appreciate the idea and the example. I'll apply this validation to ensure my documentation doesn't break with future updates. It looks like a solid approach to keeping track of changes in the theme.

Thanks again!