diff --git a/docs/user_guide/header-links.rst b/docs/user_guide/header-links.rst
index 6b410f1ce..0a87604f8 100644
--- a/docs/user_guide/header-links.rst
+++ b/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 ```` tags.
+ If you need features specific to objects in the ``svg`` class please see :ref:`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 ``