All images on the site are located in docs/img/. Images include profile pictures, software logos, and background banners. But any type of image can be added to this directory and then linked to in a given Markdown page.

Icons refer to images or decorated text that appear in-line with other text and scale with it. We use some icons that are bundled with the Material theme and some custom icons.

Many of the icons we use we use are bundled with the Material theme. See their docs for more information, including a great search bar the brings up the image of the icon as well as the code to use it in the site.

The path to any icon is used to specify it in the files. If you are using Markdown syntax to specify an icon (see below), the path is automatically formatted using the icon search bar. In other instances, you may need to give the actual icon file's path relative to its location in the Material theme, which can sometimes be difficult to discern and is not well documented. Here is the file structure of the icons within the Material theme github: Material bundled icon paths. The path itself in the Material repo is material/templates/.icons/. Use the links provided in the documentation to browse icons, and then find their associated file name at that path.

You can use these bundled icons directly in Markdown files, with the following syntax:

:fontawesome-brands-slack:

This syntax is provided in the nice icon search bar in the Material for mkdocs documentation.

In this case, the icon path is bracketed by colons (:), and slashes (/) are replaced with dashes (-).

These icons can also have custom styles applied using the following syntax:

:fontawesome-brands-slack: { .contact-icon }

Here, { .contact-icon } refers to a class in one of our custom CSS files in docs/css/. This particular one we use this on the Contact page to keep the icon as a clickable link without changing its color to red.

For more information on using icons in Markdown files see this section of the Material docs.

Markdown files can contain embedded HTML, and some of this HTML breaks the markdown icon syntax of :icon-path:. In this case Material for MkDocs provides a Jinja syntax that can be used to specify icons. Note that now the path to the icon must be provided along with the .svg file extension:

<span class="twemoji">
  {% include ".icons/fontawesome/brands/slack.svg" %} 
</span>

📝 Note: While most HTML seems to break the markdown icon syntax (:icon-path:), <span> doesn't seem to, so it still works to do <span>:icon-path: Some other content you want to style or something</span>.

For the footer icons, these are set in the mkdocs.yml configuration file under extra: social:. In this section you specify entries that will appear in the footer with both an icon and a link, e.g.:

- icon: fontawesome/brands/slack
  link: https://fas-bioinformaticspub.slack.com/

for the Bioinformatics public Slack.

Also note that the icon files all have the .svg extension, but this is not included in the path to the icon in this case.

We also use a custom icons for the FAS RC logo, the Harvard shield logo, and various others. In order to use these as icons and not images, we first must tell the site where to look for them. We do this in the mkdocs.yml configuration file with the following:

  - pymdownx.emoji:
      emoji_index: !!python/name:material.extensions.emoji.twemoji
      emoji_generator: !!python/name:material.extensions.emoji.to_svg
      options:
        custom_icons:
          - docs/assets/.icons

Note that docs/assets/ is the same folder where we put our template for the banner section on the About (home) page (docs/assets/home.html).

Now, any .svg images we place in that folder can be used as icons as described above. For example, in the footer:

    - icon: custom/fas-rc-logo
      link: https://www.rc.fas.harvard.edu/

or inline on a Markdown file, as in the Contact page:

:custom-fas-rc-logo:

See this section of the Material docs for more information on using custom icons.