Use an icon in the nav section

[NikosAlexandris]

Is it possible to use a custom icon in the nav part of the configuration file mkdocs.yml ?

Example:

nav:
  - Overview:
    - :material/some-icon: Overview: index.md

or

nav:
  - Overview:
    - :some-icon: Overview: index.md

?

[kamilkrzyskow]

Hello @NikosAlexandris,
this syntax :icon: is only processed in the Markdown contents. To add icons to your page titles you can use the icon meta key:

• https://squidfunk.github.io/mkdocs-material/reference/#setting-the-page-icon

Here is an example:

• icons-test-for-NikosAlexandris.zip
  it uses a custom icon, but you can set the path with / to any icons defined in the material theme package:
  • https://github.com/squidfunk/mkdocs-material/tree/master/material/templates/.icons

[NikosAlexandris]

Thank you. This does not directly answer the original question though. I have some Notebooks which I'd like to prepend with an icon where their title appears in the sidebar and then another pytest coverage HTML artefact which is also not a Markdown file per se. Hence, it's not possible to use the standard way of defining icon-paths inthe YAML-styled header inside a Markdown file.

Naively, in the mkdocs.yml file and in the nav section, I was trying something like :

    - 󰦕 Test Coverage: coverage.md

which is followed by

  - coverage:
      html_report_dir: docs/development/coverage_html

[alexvoss]

@kamilkrzyskow had it right. The navigation in mkdocs.yml is not processed as Markdown. While including HTML tags might give you the desired effect when combined with some CSS, at the moment the HTML would also appear in places where it does not belong, such as in the title element of the page header. Give it a try and you will see. The definition and handling of titles with more than textual content is not an easy topic, as you can see from this exchange: mkdocs/mkdocs#3357.

Perhaps this is something that could be achieved with just some CSS if you have some way of matching the navigation elements in question?

[kamilkrzyskow]

I don't really understand the coverage part, how are those 2 values connected to each other and nav in general?
Is the coverage value a plugin?
If so, then in what way does the docs/development/coverage_html have to do with anything concerning navigation?

This does not directly answer the original question though

You have asked specifically for adding an icon and provided an example, so I explained why it's not possible.

But answering the question in general. Yes, you can use text based Unicode emojis:

nav:
  - Home: index.md
  - Section:
    - 🤖 Test coverage: test/index.md

but those change the appearance based on the rendering software like Chrome / Firefox browser, PC / Mobile etc.
So I didn't even consider them as a valid approach.

---

Another approach would be to use customization:

• https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme

and modify how nav-items are rendered, and add some custom logic there to load the SVG icons based on a criteria like the file name or something else. You can look at the icon setting implementation to see how the syntax works:

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

Lines 44 to 47 in c7c8fcb

	<!-- Navigation link icon -->
	{% if nav_item.is_page and nav_item.meta.icon %}
	{% include ".icons/" ~ nav_item.meta.icon ~ ".svg" %}
	{% endif %}

---

Like Alex mentioned above you could try to use CSS to target navigation items based on their href and maybe use :after``:before classes to add the icons, but I'm not sure if this will work 🤔

• How to add animations to page icons? #6547 (reply in thread)

---

You could perhaps use some hook magic for the coverage HTML files that are not Markdown files to not include them as-is to the navigation but add a Markdown file with a YAML header and then in the on_page_content event add the HTML from those other files. This is likely the worst option, but as I said I don't see the full picture of how everything is set up.