Support for custom icons

[Andre601]

I was wondering, if this can also be used, to directly integrate custom (own) SVG icons, which are included through theme-extension.

For example having the icon.svg in a custom folder would allow to have :custom-icon:

[Andre601]

Nevermind. I can't read the readme apparently. But a question I have is, does the folder with your icons have to be on the same level as let's say the docs or theme (custom_dir) folder?

[facelessuser]

So, basically, it doesn't matter where you put it. An example:

  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
      options:
        custom_icons:
          - 'docs/src/markdown/images'

It will source the images folder above just like it sources Material's .icons folder. So I create sub directories under wherever you point it to namespace your icons.

[Andre601]

So it's options.custom_icons? Because the readme mentions a different syntax.

[facelessuser]

I think docs are wrong.

[facelessuser]

https://facelessuser.github.io/pymdown-extensions/extensions/emoji/#options

[Andre601]

Is there anything else I have to look for? I set options.custom_icons to theme/icons and made a folder at that path colled discord with the following two .svg files:

partner.svg https://hasteb.in/nomivelo.xml

verified.svg https://hasteb.in/ipegajov.xml

Using a SVG viewer/validator like https://www.rapidtables.com/web/tools/svg-viewer-editor.html did render it as it should. I tried adding it using :discord-verified: and :discord-partner: respectively but nothing happened and the text shows as above ones. The emoji extension is set up properly.

[facelessuser]

Let me verify that the sub-folders work properly. They should, and I verified images in the root, but let me, for sanity sake, verify real quick.

[facelessuser]

Using:

  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
      options:
        custom_icons:
          - 'docs/src/markdown/images'

With a logo.svg icon at docs/src/markdown/images/logo.svg and docs/src/markdown/images/custom/logo.svg. And using the following Markdown:

## Overview

:logo:

:custom-logo:

I get this:

So, I see no issues.

[facelessuser]

Did you remember to include the mkdocs-material-extensions plugin as well?

[facelessuser]

I mean with the functions?

[Andre601]

My current mkdocs.yml (From a template repo I made)

site_name: Discord Links
site_description: 'A unofficial list of popular Discord Servers'
site_author: 'Andre_601'

#
# This section uses normal HTML, so normal HTML tags and specific text like © are supported
copyright: |
  © Andre601 and all contributors.

docs_dir: docs/

#
# These three options are optional.
repo_name: Andre601/Discord-links
repo_url: https://github.com/Andre601/Discord-links
#edit_uri: tree/master/docs # If you want the Edit option/URL to be different.

nav:
  - Main:
    - Home: index.md
  - Server:
    - Discord: server/discord.md
    - Minecraft: server/minecraft.md

theme:
  name: 'material'
  #
  # Uncomment the below option to use the "theme extension" option
  # to customize certain aspects of the Material Theme.
  #
  custom_dir: 'theme'
  #
  # https://squidfunk.github.io/mkdocs-material/getting-started/#favicon
  favicon: 'assets/images/favicon.png'
  #
  # https://squidfunk.github.io/mkdocs-material/getting-started/#color-palette
  palette:
    primary: 'indigo'
    accent: 'indigo'
  #
  # https://squidfunk.github.io/mkdocs-material/getting-started/#feature-flags
  features:
    #- instant
    - tabs
  #
  # https://squidfunk.github.io/mkdocs-material/getting-started/#icons
  icon:
    logo: 'material/library'
    repo: 'material/library'

#
# You can uncomment this line together with one of the below lines to add custom CSS to the documentation.
extra_css:
#  - 'assets/css/extra.css' # Uncomment this line if you want to use both dark theme and the tabbed css.
  - 'assets/css/styling/dark.css' # Uncomment this line if you only want Dark theme
#  - 'assets/css/extensions/tabbed.css' # Uncomment this line if you only want the CSS for tabbed

extra:
  #
  # https://squidfunk.github.io/mkdocs-material/getting-started/#adding-social-links
  social:
    - icon: 'fontawesome/brands/github'
      link: 'https://github.com/Andre601/Discord-links'
  #
  # https://squidfunk.github.io/mkdocs-material/getting-started/#adding-a-web-app-manifest
  #manifest: manifest.webmanifest

markdown_extensions:
  - markdown.extensions.admonition:
  - markdown.extensions.codehilite:
      guess_lang: false
  - markdown.extensions.toc:
      permalink: true
  - pymdownx.emoji:
      emoji_index: !!python/name:materialx.emoji.twemoji
      emoji_generator: !!python/name:materialx.emoji.to_svg
      options:
        custom_icons:
          - theme/icons
  - pymdownx.magiclink:

[Andre601]

And as mentioned before did I create the directory theme/icons/discord and added the svg files to it.

[facelessuser]

What version of mkdocs-material-extensions is installed? There was at least 1 release that did not have this support. Also, what version of pymdown-extensions do you have? Only the recent version will allow this to work.

[Andre601]

PyMdown is at 7.0 and mkdocs-material-extensions is 1.0b2

I updated mkdocs-material today using pip install mkdocs-material --upgrade

[Andre601]

Updating fixed it

[facelessuser]

Cool, glad you got it working