Configuration

In the quickstart guide, you have used a simple list of favicons and Sphinx Favicon has automatically generated the corresponding HTML tags.

This section will explain how to customize the configuration and use specific tags and attributes such as apple-touch-icon.

Defining favicons

Every favicon in Sphinx Favicon is defined as a dictionary of HTML attributes.

For a single favicon, you can provide a single dictionary:

favicons = {"rel": "icon", "href": "icon.svg", "type": "image/svg+xml"}

This will generate the following HTML tag:

<link rel="icon" href="_static/icon.svg" type="image/svg+xml">

For multiple favicons, provide a list of dictionaries:

favicons = [
   {"rel": "icon", "href": "icon.svg", "type": "image/svg+xml"},
   {"rel": "icon", "sizes": "16x16", "href": "favicon-16x16.png", "type": "image/png"},
   {"rel": "icon", "sizes": "32x32", "href": "favicon-32x32.png", "type": "image/png"},
   {"rel": "apple-touch-icon", "sizes": "180x180", "href": "apple-touch-icon-180x180.png" "type": "image/png"}
]

This will generate the following HTML tags:

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

For any attributes that you don’t explicitly set, Sphinx Favicon will infer the values from your provided input. For example: if you don’t provide a type attribute, Sphinx Favicon will infer the type from the file extension. If you don’t provide a sizes attribute, Sphinx Favicon will attempt to read the pixel dimensions of the provided image.

Note

If you provide a simple list (like in the quickstart guide), Sphinx Favicon will automatically generate the dict behind the scenes.

Your list of favicons can also be a mixture of strings and dicts:

favicons = [
   "icon.svg",
   "favicon-32x32.png",
   {"rel": "apple-touch-icon", "href": "apple-touch-icon.png"},
]

This will generate the following HTML tags:

<link href="_static/icon.svg" rel="icon" type="image/svg+xml">
<link href="_static/favicon-32x32.png" sizes="32x32" rel="icon" type="image/png">
<link rel="apple-touch-icon" href="_static/_static/_static/apple-touch-icon.png" sizes="180x180" type="image/png">

Customization

You can use any parameters to define your favicon as long as they are interpreted by browsers.

The following attributes are the most commonly used ones:

href: the image location

You can define favicon images with the href attribute in two ways:

Use an absolute URL for a favicon file. For example:

"href": "https://www.sphinx-doc.org/en/master/_static/favicon.svg"

Use a local static file as a favicon. Make sure you place your local static favicon file(s) inside a directory listed in the Sphinx “html_static_path”. For example:

"href": "favicon.svg"

Note

We continue to support the legacy static_file from v0.2 for local files.

sizes: the image size

Use the sizes attribute as defined here.

For example:

"sizes": "16x16"

Sphinx Favicon automatically computes a favicon’s size if you don’t provide a value for the sizes attribute (for BMP, GIF, JPEG, JPG and PNG files).

rel: the favicon relation

Use the rel attribute to define the favicon relation. This can either be the standard “icon” and “shortcut icon”, or a custom relation like “apple-touch-icon”.

For example:

"rel": "apple-touch-icon"

If you don’t provide a value for the rel attribute, Sphinx Favicon will automatically set rel="icon".

type: the image MIME type

Use the type to define a favicon’s MIME type as defined here.

For example:

"type": "image/svg+xml"

If you don’t provide a value for the rel attribute, Sphinx Favicon will automatically extract the MIME type from the provided image file (for BMP, GIF, ICO, JPEG, JPG, PNG, and SVG files).

name: specific to msapp icons

You also have the option to specify a name attribute. This is useful for msapplication-style favicons.

If you use the name attribute, Sphinx Favicon will automatically set the rel attribute to "meta".

For example:

favicons = [
   "mstile-150x150.png",
   {"name": "msapplication-TileColor", "content": "#2d89ef"},
   {"name": "theme-color", "content": "#ffffff"},
]

This will generate the following HTML tags:

<link href="_static/mstile-150x150.png" sizes="150x150" rel="icon" type="image/png">
<meta name="msapplication-TileColor" content="#2d89ef">
<meta name="theme-color" content="#ffffff">

Tip

See the conf.py file for this documentation in the project’s GitHub repository, at tcmetzger/sphinx-favicon