jekyll-favicon

jekyll-favicon

Favicon generator and tag for Jekyll.

#favicon#jekyll#jekyll-plugins
Demo Download

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

ImageMagick

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.org

librsvg (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-bin

You 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_plugins

Usage

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.svg

This 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
dir: .
 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.

minimalacademicresumeportfoliodocumentationwikitailwindbootstrapdarkecommercegithub-pagesblog