Using custom icons in Markdown

[santaimpersonator]

I am having trouble using custom icons with Markdown.

Following, the additional icons instructions... I can get my custom icons to work as configurations in the mkdocs.yml file and as page icons. However, the markdown feature seems to fail 😞.

---

File Organization:

.
├─ overrides/
│  └─ .icons/
│     └─ logoA.svg
│     └─ logoB.svg
│     └─ test/
│        └─ logo1.svg
│        └─ logo2.svg
└─ mkdocs.yml

---

Icon used as a configuration:

# Configuration for webpage theme
theme:
  # Theme: https://squidfunk.github.io/mkdocs-material/
  name: material

  # Icon in Browser Tab (must be square img - i.e. 32x32 pixels)
  favicon: img/sfe_logo_sq.png

  # Configures icons
  icon:
    # Sets homepage icon
    logo: logoA

  # Adds overrides for stylesheets, html, etc.
  custom_dir: docs/overrides


# Included MkDocs plugins
# Add the installation of any new plugins to the ./github/workflows/mkdocs.yml file also
plugins:
  - typeset


# Included Markdown extensions
markdown_extensions:
  - admonition
  - md_in_html
  - attr_list
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
      options:
        custom_icons:
          - overrides/.icons

extra:
  # Configures social icons in the footer
  social:
    - icon: test/logo1
      link: https://www.sparkfun.com/

Result:

---

Icon used in Markdown:

:logoA:
:logoB:
:test-logo1:
:test-logo2:

Result:

[squidfunk]

Your custom_dir points to docs/.overrides, while you point pymdownx.emoji to overrides/.icons. I think if you change it to docs/overrides/.icons, it should work. Nevertheless, never put overrides in the docs_dir – they will all be copied and included with the final output.

# Included Markdown extensions
markdown_extensions:
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
      options:
        custom_icons:
          - docs/overrides/.icons # <-- NOT recommended, see explanation.

[santaimpersonator]

Unfortunately, I get this error when I set custom_dir: overrides:

bash~~ ~~@username# mkdocs serve~~ ~~ERROR - Config value 'theme': The path set in custom_dir ('/mnt/c/Users/username/Documents/GitHub/repo_name/overrides') does not exist.~~ ~~Aborted with 1 Configuration Errors!~~ ~~

Never mind... thanks, I found the problem:

1. I originally named the folder for my customized stylesheets as overrides (at the time, I didn't think the folder name mattered).
2. Later, when I started extending the theme by overriding partials , adding icons, and social cards... I was tossing all those files in the same folder.
3. Therefore, my overrides folder was actually inside the docs directory (not as I indicated 🤦):

   .
   ├─ docs/
   │  └─ .overrides/
   │    └─ .icons/
   │       └─ logoA.svg
   │       └─ logoB.svg
   │    └─ partials/
   │       └─ nav.html
   │       └─ tabs.html
   │    └─ main.html
   │    └─ extra.css
   └─ mkdocs.yml
   

4. I just had to move my overrides folder out of the docs folder, which fixed the issue. 💩