Jekyll::Livereload
DEPRECATION WARNING
With the release of Jekyll 3.7.0 Livereload support has been added to the mainline development server. With that in mind, this project will no longer be maintained or address opened issues.
What it does
Adds Livereloading support to Jekyll
What it is
Jekyll-Livereload is a plugin for the static website tool Jekyll. It adds a new options to the built-in Jekyll serve
command, --livereload
.
This plugin will automatically include the livereload.js file in the head of each page that Jekyll serves. In addition, it starts a websocket server using eventmachine that the livereload.js file will connect to.
Installation
Add this line to your site's Gemfile in the Jekyll Plugin Group:
group :jekyll_plugins do
gem 'jekyll-livereload'
end
And then execute:
bundle
Usage
This plugin was designed to work with both 3.0.5 and 3.1.3 of Jekyll.
To enable Livereload support you need to add an addition command line switch to the
jekyll serve
command: --livereload
.
If you call jekyll serve --help
for all supported serve options, you will notice
that two new options have been added.
-L, --livereload Inject Livereload.js and run a WebSocket Server
-R, --reload_port [PORT] Port to serve Livereload on
These options have been added by this plugin.
Making Livereload the default
Jekyll::Livereload supports readings configuration values from your local _config.yml
file. If you always what to use Livereload, and why wouldn't you, you can add it somewhere
in your config file like so:
# Server Config options
livereload: true # You no longer need to include --livereload
reload_port: 5678 # If you don't want to use the default port
HTTPS Support
Jekyll 3.1+ added support for running the server
command with HTTPS support.
If you include the command line switches --ssl-cert
and --ssl-key
to point to
a PEM based Certificate and Key file, then both Jekyll's WebBrick instance and the
Livereload Websocket instance will be started with HTTPS enabled.
If you use a self-signed certificate, then you will probably have errors unless you tell your browser to trust this certificate for both instances.
You will need to visit both the Jekyll serve address and the Livereload address in your browser and tell them to allow the connection. This works fine with Chrome.
For Safari you will need to click Show Certificate and then click the checkbox Always trust "" when connecting to "127.0.0.1" Where is what you entered when creating the certificate.
Not tested with other browsers, I assume the process is similar to one of the above.
Caveats
This plugin is dependent on the way Jekyll loads plugins.
Jekyll will load anything in the Gemfile
plugin group immediately after it
includes jekyll
and mercenary
, both of which need to be modified before
Jekyll initializes it's command line options.
If you attempt to use this plugin by installing it in the _plugin
directory
or by adding it to your _config.yml
file, it will not work.
This plugin will break if Jekyll upstream ever changes the placement of the call
Jekyll::PluginManager.require_from_bundler
in it's binary
command jekyll
to
be after the initialization it's command line options.
This is the reason this plugin only works if you include it in the Gemfile
Thanks
A big thanks to Alex Wood! This plugin was inspired by his Hawkins plugin for Jekyll. The reason I made this plugin was because his method did not work with the Github-Pages Gem version of Jekyll, which still used version 3.0.5 at the time of writing. His websocket server is used with very little modification and credit is given.
Also thanks to the Livereload Team, a copy of their awesome open source livereload.js is included with this plugin.