How-to implement page navigation icons for Material for MkDocs theme ($12k funding goal feature)

README.md

Implementing the "page navigation icons" feature for Material for MkDocs

Disclaimer: I have never seen the source code for Material for MkDocs Insider (the "Insider"). Anything described in this article is for demonstration purposes only. Use at your own risk.

So how does the page navigation icons feature look to you? If you find it attractive but can't wait for the $12k funding goal, you can implement this yourself and get it up and running.

Modify theme template

Start by grabbing a copy of material/partials/nav-item.html from the repository and putting it in overrides/partials/nav-items.html in your repository. Enable custom_dir: overrides as per the docs.

Then modify your local copy of the template file. Replace both occurrences of {{ nav_item.title }} directly inside an <a> tag with support for navigation icons, as shown below:

--- a.html
+++ b.html
@@ -73,7 +73,11 @@
         </label>
       {% endif %}
       <a href="{{ nav_item.url | url }}" class="md-nav__link md-nav__link--active">
-        {{ nav_item.title }}
+        {% set icon = nav_item.meta.icon %}
+        {% if icon %}
+          {% include ".icons/" ~ icon ~ ".svg" %}
+        {% endif %}
+        <span class="md-ellipsis">{{ nav_item.title }}</span>
       </a>
       {% if toc %}
         {% include "partials/toc.html" %}
@@ -82,7 +86,11 @@
   {% else %}
     <li class="{{ class }}">
       <a href="{{ nav_item.url | url }}" class="md-nav__link">
-        {{ nav_item.title }}
+        {% set icon = nav_item.meta.icon %}
+        {% if icon %}
+          {% include ".icons/" ~ icon ~ ".svg" %}
+        {% endif %}
+        <span class="md-ellipsis">{{ nav_item.title }}</span>
       </a>
     </li>
   {% endif %}

Add CSS

To make it look good, you need to add the following custom CSS to your site:

.md-nav__link svg {
  fill: currentcolor;
  flex-shrink: 0;
  width: 1.3em;
  height: 1.3em;
}

.md-nav__link svg+* {
  margin-left: .4rem;
}

.md-nav__link .md-ellipsis {
  flex-grow: 1;
  position: relative;
}

Finally, enable the Metadata extension in mkdocs.yml and go on adding icons to your pages as the documentation says.