https://github.com/tcmetzger/sphinx-favicon
Sphinx extension to add custom favicons
https://github.com/tcmetzger/sphinx-favicon
documentation documentation-generator favicon sphinx sphinx-doc sphinx-extension technical-writing
Last synced: 7 months ago
JSON representation
Sphinx extension to add custom favicons
- Host: GitHub
- URL: https://github.com/tcmetzger/sphinx-favicon
- Owner: tcmetzger
- License: mit
- Created: 2021-09-26T04:34:04.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2023-04-18T08:16:02.000Z (over 2 years ago)
- Last Synced: 2025-03-18T07:01:35.699Z (7 months ago)
- Topics: documentation, documentation-generator, favicon, sphinx, sphinx-doc, sphinx-extension, technical-writing
- Language: Python
- Homepage: https://sphinx-favicon.readthedocs.io
- Size: 92.8 KB
- Stars: 16
- Watchers: 2
- Forks: 3
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG
- License: LICENSE
Awesome Lists containing this project
README
# Sphinx Favicon
[](https://opensource.org/licenses/MIT)
[](https://github.com/psf/black)
[](https://pypi.org/project/sphinx-favicon/)
[](https://pypi.org/project/sphinx-favicon/)
[](https://github.com/tcmetzger/sphinx-favicon/actions/workflows/basic-ci.yml)
[](https://readthedocs.org/projects/sphinx-favicon/)
> **Note: Updating from Version 0.2 to Version 1.0**
>
> Between v0.2 and v1.0, the module name of the extension changed to better conform with Python standards. Please update the name used in the extension list of your `conf.py` from `sphinx-favicon` to `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"`](https://html.spec.whatwg.org/multipage/links.html#rel-icon)
or [`"apple-touch-icon"`](https://developer.apple.com/library/archive/documentation/AppleApplications/Reference/SafariWebContent/ConfiguringWebApplications/ConfiguringWebApplications.html) and
any favicon size.
The Sphinx Favicon extension gives you more flexibility than the [standard
`favicon.ico` supported by Sphinx](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_favicon). 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:
```sh
pip install sphinx-favicon
```
## Usage
After installing **sphinx-favicon**, add it to your `conf.py` extension list:
```python
extensions = ["sphinx_favicon"]
```
Then configure the favicon links using the `favicons` parameter (`html_static_path` is mandatory if you use relative path):
```python
html_static_path = ["_static"]
favicons = [
{"href": "icon.svg"}, # => use `_static/icon.svg`
{"href": "https://secure.example.com/favicon/favicon-16x16.png"},
{"href": "https://secure.example.com/favicon/favicon-32x32.png"},
{
"rel": "apple-touch-icon",
"href": "https://secure.example.com/favicon/apple-touch-icon-180x180.png",
},
]
```
Based on this configuration, Sphinx will include the following favicon information in the HTML `` element:
```html
```
For more details and more advanced usage, please see the
[documentation](https://sphinx-favicon.readthedocs.io).
## Contribution
Contributions of any kind are welcome. Please see the
[contribution](https://sphinx-favicon.readthedocs.io/en/latest/contribute.html) section of
our documentation for more information.