Search code examples
mkdocsmkdocs-material

Set a custom icon for a social link with Material for Mkdocs

I am trying to make a website with MkDocs and Material.

I am adding a social link that is supposed to use a custom icon I saved into the project's root directory.

MkDocs is trying to load the image from .icons which is somewhere in the system:

jinja2.exceptions.TemplateNotFound: '.icons/assets/twitter.svg' not found in search paths: '/home/usr/.local/lib/python3.13/site-packages/material/templates', '/home/usr/.local/lib/python3.13/site-packages/mkdocs/templates'

My project is set up like this:

website/
|-docs/
| |-assets/
| | |-twitter.svg
| |-blog/
| |-index.md
|-mkdocs.yml

My mkdocs.yml file:

site_name: my site
theme:
  palette:
    - media: "(prefers-color-scheme)"
      toggle:
        icon: material/brightness-auto
        name: Switch to light mode

    - media: "(prefers-color-scheme: light)"
      scheme: default 


      toggle:
        icon: material/brightness-7
        name: Switch to dark mode

    - media: "(prefers-color-scheme: dark)"
      scheme: slate
      toggle:
        icon: material/brightness-4
        name: Switch to system preference

  features:
    - navigation.footer
    - navigation.instant
    - navigation.instant.progress
    - navigation.tabs
  name: material

nav:
  - Docs:
    - documentation/index.md
  - Blog:
    - blog/index.md

extra:
  social:
    - icon: assets/twitter
    - link: https://x.com/

plugins:
  - search
  - blog

I tried renaming it and moving it in and out of the docs folder.

I expect MkDocs to load a custom image from inside the project.

Solution

  • i managed to fix it by extending the theme with a custom_dir. so my project set up went to this:

    website/
|-docs/
| |-blog/
| |-index.md
|-overrides/
| |-.icons/
|   |-custom/
|     |-twitter.svg
|-mkdocs.yml

    then i updated mkdocs.yml to have name and custom_dir underneath the theme:

    #...
theme:
  name: material
  custom_dir: overrides
  # everything else

extra:
  social:
    - icon: custom/twitter
      link: https://x.com/

    i found these: https://squidfunk.github.io/mkdocs-material/setup/changing-the-logo-and-icons/#logo-icon-bundled and https://squidfunk.github.io/mkdocs-material/customization/#extending-the-theme which helped me solve it