sphinx-favicon

A Sphinx extension to add custom favicons

With sphinx-favicon, you can add custom favicons to your Sphinx html documentation quickly and easily.

You can define favicons directly in your conf.py, with different rel attributes such as "icon" or "apple-touch-icon" and any favicon size.

The sphinx-favicon extension gives you more flexibility than the standard favicon.ico supported by Sphinx. It provides a quick and easy way to add the most important favicon formats for different browsers and devices.

Installation

Use pip to install sphinx-favicon in your environment:

pip install sphinx-favicon

Usage

After installing sphinx-favicon, you can configure the extension directly in conf.py (see Configuration in the Sphinx documentation for more information about this file).

There are two ways to include favicon files in your configuration:

Either use an absolute URL for a favicon file (beginning with http:// or https://). If you use an absolute URL, use the "href" parameter. See below for examples.
Or use a local static file as a favicon. Make sure you place your local static favicon file(s) inside a directory listed in Sphinx' html_static_path. If you use a relative path, use the "static-file" parameter. See below for examples.

To configure sphinx-favicon, first add "sphinx-favicon" to the list of extensions:

extensions = [
    "sphinx-favicon",
]

Next, you have several options to define favicons:

Option A: Provide detailed metadata as a list of dicts

Use a list of dicts for maximum control over the favicons added to your html document. You can use the following parameters to define a favicon:

rel: a value for the favicon's rel attribute, usually either the standard "icon" or a custom extension like "apple-touch-icon"
sizes: a value for the favicon's sizes attribute
href: the absolute URL to the favicon's image file (not required if you use the static-file parameter, see below)
type: a value specifying the favicon's MIME type
static-file: the local static file corresponding to your icon's image. Please notice this path should be relative to a directory listed in Sphinx' html_static_path (usually _static). If you define both static-file and href, the value for href will be ignored.

For example:

html_static_path = ["_static"]  # html_static_path is required if you use the "static-file" parameter

favicons = [
    {
        "rel": "icon",
        "static-file": "icon.svg",  # => use `_static/icon.svg`
        "type": "image/svg+xml",
    },
    {
        "rel": "icon",
        "sizes": "16x16",
        "href": "https://secure.example.com/favicon/favicon-16x16.png",
        "type": "image/png",
    },
    {
        "rel": "icon",
        "sizes": "32x32",
        "href": "https://secure.example.com/favicon/favicon-32x32.png",
        "type": "image/png",
    },
    {
        "rel": "apple-touch-icon",
        "sizes": "180x180",
        "href": "https://secure.example.com/favicon/apple-touch-icon-180x180.png",
        "type": "image/png",
    },
]

Based on this configuration, Sphinx will include the following favicon information in the HTML <head> element:

<link rel="icon" href="_static/icon.svg" type="image/svg+xml">
<link rel="icon" href="https://secure.example.com/favicon/favicon-16x16.png" sizes="16x16" type="image/png">
<link rel="icon" href="https://secure.example.com/favicon/favicon-32x32.png" sizes="32x32" type="image/png">
<link rel="apple-touch-icon" href="https://secure.example.com/favicon/apple-touch-icon-180x180.png" sizes="180x180" type="image/png">

Note that the relative path to the favicon's image file in the static directory will be adjusted according to each html file's location.

To make things easier for you, sphinx-favicon can also add some metadata to each favicon's <link> element automatically:

If you don't provide the "rel" argument, sphinx-favicon automatically adds rel="icon".
if you don't provide the "type" argument, sphinx-favicon automatically determines the MIME type based on the image's filename extension.
Currently, sphinx-favicon is not able to automatically read a file's size in pixels as required for the "size" argument. If you don't provide information about a favicon file's pixel size, the "size" argument will be omitted for that favicon image.

Therefore, the following simplified configuration generates the exact same HTML result as above:

html_static_path = ["_static"]

favicons = [
    {"static-file": "icon.svg"},  # => use `_static/icon.svg`
    {
        "sizes": "16x16",
        "href": "https://secure.example.com/favicon/favicon-16x16.png",
    },
    {
        "sizes": "32x32",
        "href": "https://secure.example.com/favicon/favicon-32x32.png",
    },
    {
        "rel": "apple-touch-icon",
        "sizes": "180x180",
        "href": "https://secure.example.com/favicon/apple-touch-icon-180x180.png",
    },
]

Option B: Provide a single dict for just one favicon

If you want to add just one custom favicon, you can also use a simple dict in conf.py:

favicons = {
    "rel": "apple-touch-icon",
    "sizes": "180x180",
    "href": "https://secure.example.com/favicon/apple-touch-icon-180x180.png",
    }

Based on this configuration, Sphinx will include the following favicon information in the <head> of every HTML file:

<link rel="apple-touch-icon" href="https://secure.example.com/favicon/apple-touch-icon-180x180.png" sizes="180x180" type="image/png">

Option C: Provide a list of local favicon files or URLs

The quickest way to add favicons is just adding a list of favicon URLs to conf.py.

html_static_path = ["_static"]
favicons = [
    "icon.svg",  # => `_static_/icon.svg`
    "https://secure.example.com/favicon/favicon-16x16.gif",
    "https://secure.example.com/favicon/favicon-32x32.png",
    "https://secure.example.com/favicon/apple-touch-icon-180x180.png",
]

Based on this configuration, Sphinx will include the following favicon information in the HTML <head> element:

<link rel="icon" href="_static/icon.svg" type="image/svg+xml">
<link rel="icon" href="https://secure.example.com/favicon/favicon-16x16.gif" type="image/gif">
<link rel="icon" href="https://secure.example.com/favicon/favicon-32x32.png" type="image/png">
<link rel="icon" href="https://secure.example.com/favicon/apple-touch-icon-180x180.png" type="image/png">

Please note that if your URLs don't start with https://, http:// or /, they will be considered a static file inside a directory listed in Sphinx' html_static_path.

Contribute

To contribute to this extension, please open an issue or make a pull request to the repository on GitHub.

Additional dependencies for development are listed in the file dev-requirements.txt in the repository. Use pytest -vv to run tests. All Python code should be formatted with Black.

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

sphinx-favicon-0.2.tar.gz (6.6 kB view details)

Uploaded Nov 16, 2021 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

sphinx_favicon-0.2-py3-none-any.whl (6.4 kB view details)

Uploaded Nov 16, 2021 Python 3

File details

Details for the file sphinx-favicon-0.2.tar.gz.

File metadata

Download URL: sphinx-favicon-0.2.tar.gz
Upload date: Nov 16, 2021
Size: 6.6 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/3.6.0 importlib_metadata/4.8.2 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.5

File hashes

Hashes for sphinx-favicon-0.2.tar.gz
Algorithm	Hash digest
SHA256	`73436a1f5f80c4fcae6eadd2520b9c2bc6c1aec0d91d153b3774359bdd103a58`
MD5	`758925ab5b4669f214d0be843f033caa`
BLAKE2b-256	`187f044fcd612f45627154738cd9f86ec12c0e9ef4b9c71537f5abbcc2f79bde`

See more details on using hashes here.

File details

Details for the file sphinx_favicon-0.2-py3-none-any.whl.

File metadata

Download URL: sphinx_favicon-0.2-py3-none-any.whl
Upload date: Nov 16, 2021
Size: 6.4 kB
Tags: Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/3.6.0 importlib_metadata/4.8.2 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.5

File hashes

Hashes for sphinx_favicon-0.2-py3-none-any.whl
Algorithm	Hash digest
SHA256	`0b17cb0f9b97fb99172d47fb11fbdd0aadb26cbe0f6368e81843176ca18d06e6`
MD5	`83cb71eccb0bf82218b2336cadf48b35`
BLAKE2b-256	`d6b601a38614ce3e97d699068832a968883c5ebeadcf83e2e2bec1d1df95dbb4`