Set icon in sections/external links in the navigation

[joapuiib]

I would like to set an icon in the section titles in the navigation, just as icons set in pages via page.meta.icon.

In the image, I would like to set an icon before DAM1s and DAW1

I have looked at the code, but it seems it's only supported in pages.

mkdocs-material/material/templates/partials/nav-item.html

Lines 14 to 16 in 8df393d

	{% if nav_item.is_page and nav_item.meta.icon %}
	{% include ".icons/" ~ nav_item.meta.icon ~ ".svg" %}
	{% endif %}

I could try to override that macro to include icons in sections, but my question is: Which would be the best way to specify the icon in a section?

I have thought of different options:

• Specify it in the config.nav: That would imply changes in the nav config option in Mkdocs, so I'm not sure if it's the best option.
• Use the markdown :icon: syntax. That would require some kind of parsing. Could it be done in the template?
• Use a .meta file in the section directory. This would require some plugin or hook to read its contents and store it somewhere. The Section class doesn't have a meta attribute.

[kamilkrzyskow]

Hello @joapuiib,

Sections don't have any metadata by default, and the main issue is how to store and link the icon to a specific section, I believe there is only the title you could use as the Section metadata to distinguish between them, and this could lead to some sort of "side effect" when 2 sections have the same title. I don't think there is any best option, of adding this connection, as most of them are somewhat intrusive.

If the side effect of duplicate Section titles doesn't concern you, my suggestion would be to make use of either the theme or extra config options in the mkdocs.yml file to store and link icons to Section titles. To mitigate the side effect you could create a direct (mirror) copy of the navigation tree inside theme or extra which would be a second layer of connection, because you could use the parent node and their title to distinguish between Sections.

---

Specify it in the config.nav: That would imply changes in the nav config option in Mkdocs, so I'm not sure if it's the best option.

IIRC you're making your own theme, extending the Material theme, so you could go the route of modifying the MkDocs nav logic to support an icon value and read it inside the template, but this would involve overriding the nav logic before it's loaded from the mkdocs.yml, so somebody could see it as too hacky. You could also try extending the logic of awesome-pages-plugin to both support such value in the .pages files and include it in the final Navigation object.

Use a .meta file in the section directory. This would require some plugin or hook to read its contents and store it somewhere. The Section class doesn't have a meta attribute.

This would be the less hacky approach, as you would work on the parsed and validated Navigation object in the event loop and would simply add the data from the .meta file. I think there is no connection with the directory structure and the navigation tree itself, so I would also recommend to create a duplicate mirror of the navigation tree in the .meta file.

Use the markdown :icon: syntax. That would require some kind of parsing. Could it be done in the template?

I don't think this approach is needed, as the include directive allows to add the SVG files?
The processing of Markdown syntax is done after the on_page_markdown event, and it's not available for the templates by default. You could likely add a filter function, similar to how there is the date filter for the Blog plugin, to pass in such text value and parse it, but this doesn't solve the issue where should the value be read from.

• mkdocs-material/src/plugins/blog/plugin.py

  Line 323 in 8df393d

  env.filters["date"] = date_filter

• mkdocs-material/src/templates/blog-post.html

  Line 96 in 8df393d

  {{- page.config.date.created | date -}}

[joapuiib]

Thanks for your detailed answer! It is really inspiring!
I've managed to do it with awesome-pages-plugin and the filter idea.

• First of all, I have written a plugin that creates two filters extract_icon and remove_icon:

from mkdocs.plugins import BasePlugin
import re

# This regex allows to match a icon with no text
ICON_RE = re.compile(r'^:(\S+):(?: ([^\n]+))?$')


def extract_icon(section_title):
    match = ICON_RE.match(section_title)
    if match:
        return match.group(1)
    return None


def remove_icon(section_title):
    match = ICON_RE.match(section_title)
    if match:
        return match.group(2) or ''
    return section_title


class SectionIconsPlugin(BasePlugin):
    def on_env(self, env, config, files):
        if not self.config.get('enabled', True):
            return

        env.filters['extract_icon'] = extract_icon
        env.filters['remove_icon'] = remove_icon

This plugin parses icons at the start of the title with the syntax :icon: Section title.

• With those filers, I've modified the render_content macro in the nav_item.html partial, so the icon can be extracted from the section title.

{% macro render_content(nav_item, ref = nav_item) %}
  {% set title = ref.title %}
  {% if nav_item.is_page and nav_item.meta.icon %}
    {% include ".icons/" ~ nav_item.meta.icon ~ ".svg" %}
  {% endif %}
  {% if "sectionicons" in plugins and nav_item.is_section %}
    {% set section_icon = ref.title | extract_icon %}
    {% if section_icon %}
      {% set title = ref.title | remove_icon %}
      {% include ".icons/" ~ section_icon ~ ".svg" %}
    {% endif %}
  {% endif %}
  <span class="md-ellipsis">
    {{ title }}
  </span>
  {% if nav_item.is_page and nav_item.meta.status %}
    {{ render_status(nav_item, nav_item.meta.status) }}
  {% endif %}
{% endmacro %}

• I've defined the title in the .pages files using awesome-pages-plugin.

nav:
    - ...
    - ":material/pencil-outline: Section title": section_directory

I think it should work without awesome-pages-plugin if the section title is specified in config, but I've not tested it.

• It works! 😄

I could write in a separate plugin package, but in order to work, people should have to modify the nav_item.html partial.

Gently pinging @squidfunk. Do you think this feature could be useful?

Any considerations/fixes about the syntax or implementation made are more than welcome.

---

While working on this, I got a new doubt.

In order to override the render_content macro inside the nav_item.html partial, I have had to copy the entire original file inside my custom theme, so the other macros are still available, and then, make my modifications.

Is there a way to override a single macro and still use the previous defined macros?.

[kamilkrzyskow]

Very nice solution 👍, once again less complicated than mine 😅. Thanks for sharing ❤️

As the title contains a special token that gets stripped afterwards it should also work without the awesome-pages-plugin.
Also it could be simplified with a single :i: / ; separator to not require regex extraction.

Is there a way to override a single macro and still use the previous defined macros?

I don't think so, no, but then again I never tried it 🤔

The Jinja2 templates are parsed into a Python script blob, and the defined blocks in the base.html can be overridden in the files that extend it. Also when developing mkdocs-nype theme I tested the double extend chain of Material base.html -> Nype nype-base.html -> Project override main.html and the block overrides are still working, so the block scopes are properly being managed at a global level when working from top to bottom of the import chain.

However, I don't know how are the macros, that are defined in a lower level "node", defined in the final parsed code.

[joapuiib]

Thanks for the insight!

I'll try to investigate and I'll let you know if I figure something out.

Many thanks for your help ❤️

[joapuiib]

Just in case it helps someone, I've modified the template so it allows icons in external links in the navigation:

{% macro render_content(nav_item, ref = nav_item) %}
  {% set title = ref.title %}
  {% if nav_item.is_page and nav_item.meta.icon %}
    {% include ".icons/" ~ nav_item.meta.icon ~ ".svg" %}
  {% endif %}
  {% if "sectionicons" in config.plugins and (nav_item.is_section or nav_item.is_link) %}
    {% set section_icon = ref.title | extract_icon %}
    {% if section_icon %}
      {% set title = ref.title | remove_icon %}
      {% include ".icons/" ~ section_icon ~ ".svg" %}
    {% endif %}
  {% endif %}
  <span class="md-ellipsis">
    {{ title }}
  </span>
  {% if nav_item.is_page and nav_item.meta.status %}
    {{ render_status(nav_item, nav_item.meta.status) }}
  {% endif %}
{% endmacro %}

No change in the plugin is needed.

[joapuiib]

In order to set the icon in the section title on mobile screens, an adjustment has been made:

In nav-item.html partial:

mkdocs-material/src/templates/partials/nav-item.html

Lines 214 to 216 in 47fc7d5

	<label class="md-nav__title" for="{{ path }}">
	<span class="md-nav__icon md-icon"></span>
	{{ nav_item.title }}

<nav class="md-nav" data-md-level="{{ level }}" aria-labelledby="{{ path }}_label" aria-expanded="{{ nav_item.active | tojson }}">
  <label class="md-nav__title" for="{{ path }}">
    <span class="md-nav__icon md-icon"></span>
    {% set title = nav_item.title %}
    {% if "sectionicons" in config.plugins and nav_item.is_section %}
      {% set section_icon = nav_item.title | extract_icon %}
      {% if section_icon %}
        {% set title = nav_item.title | remove_icon %}
        {% include ".icons/" ~ section_icon ~ ".svg" %}
      {% endif %}
    {% endif %}
    {{ title }}
  </label>

In this case, a CSS is needed to set the size of the icon:

.md-nav__title svg {
    fill: currentcolor;
    flex-shrink: 0;
    height: 1.3em;
    position: relative;
}

This styles are a copy of:

mkdocs-material/src/templates/assets/stylesheets/main/components/_nav.scss

Lines 120 to 128 in 47fc7d5

	// Navigation link icon
	svg {
	// Hack: Safari has another bug where SVGs disappear on hover - same fix
	// as above via `position: relative` - see https://t.ly/5fSj1
	position: relative;
	flex-shrink: 0;
	height: 1.3em;
	fill: currentcolor;
	}

---

Just in case, the full nav-item.html partial with the modifications can be found at my custom theme.

[ojacques]

Great discussion and insights. Another way to achieve this is through awesome-pages plugin, and using Unicode emojis in the alternate title, which are now largely supported by systems (client side). On Windows, you get them with the windows key + ";". The challenge is that they are not coming from the material icon library.

Example of a .pages:

nav:
  - "🏠 DOFLinx": README.md
  - "🚀 Getting Started": getting-started
  - "⚙️ Parameters": parameters
  - "🕹️ Systems": systems
  - "🌟 Misc": Misc
  - "🆘 Help": 07_Help.md
  - ...