Sphinx Favicon

1.1.0 · active · verified Thu Apr 16

Sphinx Favicon is an active Sphinx extension, currently at version 1.1.0, that enhances the ability to add custom favicons to Sphinx HTML documentation. It allows users to define favicons directly in `conf.py` with various attributes like `rel`, `sizes`, `href`, or `name`, providing more flexibility than Sphinx's default `favicon.ico` support. The library maintains a steady release cadence with recent updates focusing on bug fixes and dependency modernization.

Common errors

```
Unknown extension: sphinx-favicon
```
cause Using the old extension module name 'sphinx-favicon' in `conf.py` after upgrading to version 1.0 or newer.

fix Change the entry in your `conf.py` from `extensions = ['sphinx-favicon']` to `extensions = ['sphinx_favicon']`.
```
Favicon not appearing in browser tabs or bookmarks.
```
cause The favicon image path is incorrect, or `html_static_path` is not configured correctly for relative paths, or the favicon definition itself is malformed.

fix Verify that your favicon images exist in the specified `_static` directory (or wherever `html_static_path` points). Ensure `html_static_path` is correctly set in `conf.py`. Double-check the `href` values in your `favicons` list for typos.

Warnings

breaking The extension module name changed from `sphinx-favicon` to `sphinx_favicon` in version 1.0. Older configurations using `sphinx-favicon` in the `extensions` list will break.
Fix: Update your `conf.py` file: change `extensions = ['sphinx-favicon']` to `extensions = ['sphinx_favicon']`.
gotcha When using relative paths for your favicon images (e.g., `"href": "icon.png"`), the `html_static_path` variable MUST be defined in `conf.py` and point to the directory containing your static files. If omitted, Sphinx may not locate your favicons.
Fix: Ensure `html_static_path = ['_static']` (or your chosen static directory) is set in your `conf.py` file, and your favicon images are within that directory.
gotcha Sphinx has a built-in `html_favicon` configuration option for a single ICO, PNG, SVG, or GIF favicon. While `sphinx-favicon` enhances this, using both `html_favicon` and `favicons` simultaneously can lead to unexpected behavior or redundant output. Prioritize `sphinx-favicon`'s `favicons` for comprehensive control.
Fix: If using `sphinx-favicon`, rely on the `favicons` list for all your favicon definitions for best results. Avoid setting `html_favicon` in `conf.py` if `favicons` provides the desired functionality.

Install

pip install sphinx-favicon Install with pip

Imports

Extension Enablement
wrong:
```
extensions = ['sphinx-favicon']
```
correct:
```
extensions = ['sphinx_favicon']
```
Between v0.2 and v1.0, the module name of the extension changed from `sphinx-favicon` to `sphinx_favicon` to conform with Python standards. Ensure your `conf.py` is updated.

Quickstart

To quickly integrate `sphinx-favicon` into your Sphinx project, first ensure your favicon images (e.g., `icon.png`, `apple-touch-icon.png`) are placed in your `_static` directory. Then, modify your `conf.py` file to include `sphinx_favicon` in your `extensions` list and configure the `favicons` list with paths to your images. The `html_static_path` must be defined if using relative paths for favicons.

# conf.py

# Add the extension to the list of enabled Sphinx extensions
extensions = [
    'sphinx.ext.autodoc',
    'sphinx_favicon',
]

# Configure the directory for static files (where your favicon images will be)
html_static_path = ['_static']

# Define your favicons. Ensure 'icon.png' exists in your _static directory.
favicons = [
    {"href": "icon.png"},
    {"rel": "apple-touch-icon", "href": "apple-touch-icon.png"}
]

view raw JSON →