Jekyll Favicon
This Jekyll plugin adds:
- a generator for favicons (ICO, PNG, SVG), webmanifests, and browserconfig files
- a tag for the rendinering of all the corresponding links and metadata needed
Tested with:
- Jekyll 3.6 to 3.7, ruby 2.6 to 2.7
- Jekyll 3.8 to 4.2, ruby 2.6 to 3.1
Prerequisites
Check if it is already installed by running:
$ convert --version | grep Version
Version: ImageMagick 7.0.8-46 Q16 x86_64 2019-05-19 https://imagemagick.orglibrsvg (optional)
If you are having pixeled icons or if you have a problem converting SVG files, you may need to install the package librsvg2-bin. For example, in Ubuntu/Debian systems:
sudo apt install librsvg2-binYou may need to install librsvg before installing the RSVG renderer.
Check the devcontainer's Dockerfile for more practical details.
Installation
Add this line to your application's Gemfile:
gem 'jekyll-favicon', '~> 1.1.0', group: :jekyll_pluginsUsage
If you are going to use this plugin in a hosted build/service, be sure that they include your plugins as part of the process. You can check gh-pages branch for a working example.
As Github Pages doesn't load custom plugins, this plugin won't be included on the build process. As a workaround, you can build your site and push all files (for example, build to docs, version it and push it, although this works only for project pages).
Generator
By installing the plugin, it will be automatically activated without further configurations.
You can override these settings in your sites's _config.yml. The simplest configuration would be this:
favicon:
source: custom-favicon-png-or.svgThis plugin works best if you use an SVG with a square viewbox as the source, but you can also use a PNG instead (at least 558x588). Check the fixtures favicon.svg or favicon.png as examples.
Favicon tag
To get the links and meta, just add the favicon tag {% favicon %}. For example, on your index.html
---
---
<!DOCTYPE html>
<html>
<head>
{% favicon %}
</head>
<body>
</body>
</html>Configuration
The plugin customization goes in the favicon key in the _config.yml file. There are four key parameters:
| attribute name | type | default | description |
|---|---|---|---|
| source | hash/string | name: favicon.svg |
SVG or PNG file relative to site's source. Any favicon without explicit source will use this attribute as default. |
| background | string | transparent |
Color keyword or Hex representation. Any favicon without explicit convert background will use this attribute as default. |
| dir | string | . |
Path relative to site's source. Any favicon without explicit source dir will use this attribute as default. |
| assets | array | see defaults | Array of asset configuration. Any asset define here will be controlled with this plugin. |
Assets
The assets is an array of file spec:
| attribute name | type | default | description |
|---|---|---|---|
| name | string | file's basename. Required. | |
| dir | string/symbol | :site_dir |
file's dir, relative to site's destination |
| source | hash | file's source. Required. | |
| convert | hash | {} |
see convert defaults |
| tags | array | [] |
see tags defaults |
| refer | hash | [] |
see refer defaults |
Symbol values:
-
:background: favicon's global background -
:site_dir: favicon's global dir -
:href: favicons absolute URL path
Convert
The convert configuration is specific for each type of convertion: SVG to ICO/PNG/SVG and PNG to ICO/PNG.
| attribute name | type | default | description |
|---|---|---|---|
| alpha | string | see convert config | see imagemagick alpha docs |
| background | string/symbol | see convert config | see imagemagick background docs |
| define | string/symbol | see convert config | see imagemagick define docs |
| extent | string/symbol | see convert config | see imagemagick extent docs |
| gravity | string | see convert config | see imagemagick gravity docs |
| resize | string | see convert config | see imagemagick resize docs |
| size | string | see convert config | see imagemagick size docs |
Symbol values:
-
:auto: if sizes is not a square, then sizes -
:max: 3 times the largest dimension
Tags
The tags configuration is a list of hashes with only one key, link or meta, and only one value, a hash with the HTML attributes associated to the key. See tags defaults for more details.
Refer
The refer configuration is a list of hashes with only one key, webmanifest or browserconfig, and only one value, a hash that will override the associated file. See refer defaults for more details.
Development
If you want to add something, just make a PR. There is a lot to do:
- Tests more cases
- Keep updated the favicons and files needed with modern browsers
Contributing
Bug reports and pull requests are welcome on GitHub at https://github.com/afaundez/jekyll-favicon. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the Contributor Covenant code of conduct.
License
The gem is available as open-source under the terms of the MIT License.
Code of Conduct
Everyone interacting in the Jekyll Favicon project’s codebases, issue trackers, chat rooms, and mailing lists is expected to follow the code of conduct.
Acknowledgments
Notoriously inspired by jekyll/jekyll-seo-tag and jekyll/jekyll-sitemap.