Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add instructions for custom SVG icons #1490

Merged
merged 11 commits into from
Oct 30, 2023
70 changes: 70 additions & 0 deletions docs/user_guide/header-links.rst
Original file line number Diff line number Diff line change
Expand Up @@ -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:
Expand Down Expand Up @@ -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:
12rambau marked this conversation as resolved.
Show resolved Hide resolved

#. 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
12rambau marked this conversation as resolved.
Show resolved Hide resolved

12rambau marked this conversation as resolved.
Show resolved Hide resolved
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
12rambau marked this conversation as resolved.
Show resolved Hide resolved
#. 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
Expand Down
Loading