Add ability to specify custom icon images

docs/conf.py

@@ -88,7 +88,13 @@
             "name": "PyPI",
             "url": "https://pypi.org/project/pydata-sphinx-theme",
             "icon": "fas fa-box",
-        }
+        },
+        {
+            "name": "PyData",
+            "url": "https://pydata.org",
+            "icon": "_static/pydata-logo-square.png",
+            "type": "local",
+        },
     ],
     "use_edit_page_button": True,
     "show_toc_level": 1,

docs/user_guide/configuring.rst

@@ -34,8 +34,45 @@ If you'd like it to link to another page or use an external link instead, use th
 Configure icon links
 ====================
 
-If you'd like icon links to show up to the right of your main navigation bar, use the
-following configuration:
+You can add icon links to show up to the right of your main navigation bar.
+
+These links take the following form:
+
+.. code:: python
+
+   html_theme_options = {
+       ...
+       "icon_links": [
+           {
+               # Label for this link
+               "name": "GitHub",
+               # URL where the link will redirect
+               "url": "https://github.com/<your-org>/<your-repo>",  # required
+               # Icon class (if type=='fontawesome'), or path to local image (if type=='local')
+               "icon": "fab fa-github-square",
+               # Whether icon should be a FontAwesome class, or a local file
+               "type": "fontawesome OR local",  # Default is fontawesome
+           }
+      ]
+   }
+
+There are two kinds of icons you can use, described below:
+
+FontAwesome icons
+-----------------
+
+`FontAwesome <https://fontawesome.com/>`_ is a collection of icons that are
+commonly used in websites. They include both generic shape icons (e.g., "arrow-down"),
+as well as brand-specific icons (e.g. "github").
+
+You can use FontAwesome icons by specifying ``type=="fontawesome"``, and
+specifying a FontAwesome class in the ``icon`` value.
+The value of ``icon`` can be any full
+`FontAwesome 5 Free <https://fontawesome.com/icons?d=gallery&m=free>`__ icon.
+In addition to the main icon class, e.g. ``fa-cat``, the "style" class must
+also be provided e.g. `fab` for *branding*, or `fas` for *solid*.
+
+Here are several examples:
 
 .. code:: python
 
@@ -46,28 +83,24 @@ following configuration:
                "name": "GitHub",
                "url": "https://github.com/<your-org>/<your-repo>",
                "icon": "fab fa-github-square",
+               "type": "fontawesome",
            },
            {
                "name": "GitLab",
                "url": "https://gitlab.com/<your-org>/<your-repo>",
                "icon": "fab fa-gitlab",
+               "type": "fontawesome",
            },
            {
                "name": "Twitter",
                "url": "https://twitter.com/<your-handle>",
                "icon": "fab fa-twitter-square",
+               # The default for `type` is `fontawesome` so it is not required here
            },
        ],
        ...
    }
 
-
-The value of ``icon`` can be any full
-`FontAwesome 5 Free <https://fontawesome.com/icons?d=gallery&m=free>`__ icon.
-In addition to the main icon class, e.g. ``fa-cat``, the "style" class must
-also be provided e.g. `fab` for *branding*, or `fas` for *solid*.
-
-
 .. Hint::
 
    To get custom colors like "Twitter blue", use the following in your CSS,
@@ -81,8 +114,35 @@ also be provided e.g. `fab` for *branding*, or `fas` for *solid*.
 
    This has already been added for the brands that have *shortcuts*.
 
-The below are shortcuts for commonly-used services, but may be removed in a future
-release in favor of ``icon_links``:
+Local image icons
+-----------------
+
+If you'd like to display an icon image that is not in the FontAwesome icons library,
+you may instead specify a path to a local image that will be used for the icon.
+To do so, use ``type=="local"``, and add a path to an image
+**relative to your documentation root** in the ``icon`` value.
+Here is an example:
+
+.. code:: python
+
+   html_theme_options = {
+       ...
+       "icon_links": [
+           {
+               "name": "PyData",
+               "url": "https://pydata.org",
+               "icon": "_static/pydata-logo-square.png",
+               "type": "local",
+           },
+       ],
+       ...
+   }
+
+Icon Link Shortcuts
+-------------------
+
+There are a few shortcuts supported to minimize configuration for commonly-used services.
+These may be removed in a future release in favor of ``icon_links``:
 
 .. code:: python
 

src/pydata_sphinx_theme/assets/styles/index.scss

@@ -457,6 +457,10 @@ nav.bd-links {
       color: #0052cc;
     }
   }
+
+  img.icon-link-image {
+    height: 1.5em;
+  }
 }
 
 /* TOC section headers */

src/pydata_sphinx_theme/theme/pydata_sphinx_theme/icon-links.html

@@ -1,8 +1,14 @@
-{%- macro icon_link_nav_item(url, icon, name) -%}
+{%- macro icon_link_nav_item(url, icon, name, type) -%}
   {%- if url | length > 2 %}
         <li class="nav-item">
           <a class="nav-link" href="{{ url }}" rel="noopener" target="_blank" title="{{ _(name) }}">
+            {%- if type == "fontawesome" -%}
             <span><i class="{{ icon }}"></i></span>
+            {%- elif type == "local" -%}
+            <img src="{{ pathto(icon, 1) }}" class="icon-link-image"/>
+            {%- else %}
+            <span>Incorrectly configured icon link. Type must by `fontawesome` or `local`.</span>
+            {%- endif -%}
             <label class="sr-only">{{ _(name) }}</label>
           </a>
         </li>
@@ -11,12 +17,12 @@
 
       <ul id="navbar-icon-links" class="navbar-nav" aria-label="{{ _(theme_icon_links_label) }}">
         {%- block icon_link_shortcuts -%}
-        {{ icon_link_nav_item(theme_github_url, "fab fa-github-square", "GitHub") -}}
-        {{ icon_link_nav_item(theme_gitlab_url, "fab fa-gitlab", "GitLab") -}}
-        {{ icon_link_nav_item(theme_bitbucket_url, "fab fa-bitbucket", "Bitbucket") -}}
-        {{ icon_link_nav_item(theme_twitter_url, "fab fa-twitter-square", "Twitter") -}}
+        {{ icon_link_nav_item(theme_github_url, "fab fa-github-square", "GitHub", "fontawesome") -}}
+        {{ icon_link_nav_item(theme_gitlab_url, "fab fa-gitlab", "GitLab", "fontawesome") -}}
+        {{ icon_link_nav_item(theme_bitbucket_url, "fab fa-bitbucket", "Bitbucket", "fontawesome") -}}
+        {{ icon_link_nav_item(theme_twitter_url, "fab fa-twitter-square", "Twitter", "fontawesome") -}}
         {% endblock -%}
         {%- for icon_link in theme_icon_links -%}
-        {{ icon_link_nav_item(icon_link["url"], icon_link["icon"], icon_link["name"]) -}}
+        {{ icon_link_nav_item(icon_link["url"], icon_link["icon"], icon_link["name"], icon_link.get("type", "fontawesome")) -}}
         {%- endfor %}
       </ul>

tests/test_build.py

@@ -91,6 +91,46 @@ def test_toc_visibility(sphinx_build_factory):
     assert "visible" not in index_html.select(".toc-h3 ul")[0].attrs["class"]
 
 
+def test_icon_links(sphinx_build_factory, file_regression):
+    html_theme_options_icon_links = {
+        "icon_links": [
+            {
+                "name": "FONTAWESOME",
+                "url": "https://site1.org",
+                "icon": "FACLASS",
+                "type": "fontawesome",
+            },
+            {
+                "name": "FONTAWESOME DEFAULT",
+                "url": "https://site2.org",
+                "icon": "FADEFAULTCLASS",
+                # No type so we can test that the default is fontawesome
+            },
+            {
+                "name": "LOCAL FILE",
+                "url": "https://site3.org",
+                "icon": "emptylogo.png",  # Logo is our only test site img
+                "type": "local",
+            },
+            {
+                "name": "WRONG TYPE",
+                "url": "https://site4.org",
+                "icon": "WRONG TYPE",
+                # Because the type is inccorect, this should output an error `span`
+                "type": "incorrecttype",
+            },
+        ]
+    }
+    confoverrides = {"html_theme_options": html_theme_options_icon_links}
+
+    sphinx_build = sphinx_build_factory("base", confoverrides=confoverrides).build()
+    # Navbar should have the right icons
+    icon_links = sphinx_build.html_tree("index.html").select("#navbar-icon-links")[0]
+    file_regression.check(
+        icon_links.prettify(), basename="navbar_icon_links", extension=".html"
+    )
+
+
 def test_logo(sphinx_build_factory):
     """Test that the logo is shown by default, project title if no logo."""
     sphinx_build = sphinx_build_factory("base").build()

tests/test_build/navbar_icon_links.html

@@ -0,0 +1,43 @@
+<ul aria-label="Icon Links" class="navbar-nav" id="navbar-icon-links">
+ <li class="nav-item">
+  <a class="nav-link" href="https://site1.org" rel="noopener" target="_blank" title="FONTAWESOME">
+   <span>
+    <i class="FACLASS">
+    </i>
+   </span>
+   <label class="sr-only">
+    FONTAWESOME
+   </label>
+  </a>
+ </li>
+ <li class="nav-item">
+  <a class="nav-link" href="https://site2.org" rel="noopener" target="_blank" title="FONTAWESOME DEFAULT">
+   <span>
+    <i class="FADEFAULTCLASS">
+    </i>
+   </span>
+   <label class="sr-only">
+    FONTAWESOME DEFAULT
+   </label>
+  </a>
+ </li>
+ <li class="nav-item">
+  <a class="nav-link" href="https://site3.org" rel="noopener" target="_blank" title="LOCAL FILE">
+   <img class="icon-link-image" src="emptylogo.png">
+    <label class="sr-only">
+     LOCAL FILE
+    </label>
+   </img>
+  </a>
+ </li>
+ <li class="nav-item">
+  <a class="nav-link" href="https://site4.org" rel="noopener" target="_blank" title="WRONG TYPE">
+   <span>
+    Incorrectly configured icon link. Type must by `fontawesome` or `local`.
+   </span>
+   <label class="sr-only">
+    WRONG TYPE
+   </label>
+  </a>
+ </li>
+</ul>