docs: add instructions for custom SVG icons

docs/user_guide/header-links.rst

@@ -145,6 +145,17 @@ Image icons
 
 If you'd like to display an icon image that is not in the FontAwesome icons library,
 you may instead specify a URL or a path to a local image that will be used for the icon.
+You may also use ``.svg`` images as if they were FontAwesome with a little additional setup.
+
+Bitmap image icons
+~~~~~~~~~~~~~~~~~~
+
+For all bitmap image icons such as ``.png``, ``.jpg``, etc., you must specify ``type`` as local.
+
+.. note::
+
+    All icon images with ``"type": "local"`` are inserted into the document using ``<img>`` tags.
+    If you need features specific to objects in the ``svg`` class please see :ref:`svg image icons <svg-image-icons>`
 
 **To display an image on the web**, use ``"type": "url"``, and provide a URL to an image in the ``icon`` value.
 For example:
@@ -188,6 +199,65 @@ For example:
 
    Use ``.svg`` images for a higher-resolution output that behaves similarly across screen sizes.
 
+.. _svg-image-icons:
+
+SVG image icons
+~~~~~~~~~~~~~~~
+
+In order to make use of the full feature set of ``.svg`` images provided by HTML you will need
+to set up the ``.svg`` to be used as a FontAwesome type icon. This is a fairly straightforward process:
+
+#. Copy the contents of ``custom-icon.js`` - located within the ``docs`` tree - into an appropriate directory of your documentation
+   source (typically ``source/js``) and rename the file however you like. Highlighted below are the lines which must be modified
+
+   .. code:: javascript
+
+     prefix: "fa-custom",
+     iconName: "pypi",
+     icon: [
+       17.313, // viewBox width
+       19.807, // viewBox height
+       [], // ligature
+       "e001", // unicode codepoint - private use area
+       "m10.383 0.2-3.239 ...", // string definined SVG path
+     ],
+
+
+#. Update the following file contents:
+
+   #.  ``iconName``  to be one of our choosing
+   #.  Change the viewbox height and width to match that of your icon
+   #.  Replace the SVG path string with the path which defines your custom icon
+
+#. Add the relative path from your source directory to the custom javascript file to your ``conf.py``:
+
+   .. code:: python
+
+      html_js_files = [
+         ...
+         "js/pypi-icon.js",
+         ...
+      ]
+
+#. Set up the icon link in the ``html_theme_options`` as a FontAwesome icon:
+
+   .. code:: python
+
+      html_theme_options = [
+         ...
+         "icon_links": [
+            {
+               "name": "PyPI",
+               "url": "https://www.pypi.org",
+               "icon": "fa-custom fa-pypi",
+               "type": "fontawesome",
+            },
+         ],
+         ...
+      ]
+
+That's it, your icon will now be inserted with the ``<svg>`` tag and not ``<img>``! You can reference your custom FontAwesome icon in CSS using ``fa-<custom-name>``.
+
 .. _icon-link-shortcuts:
 
 Icon Link Shortcuts