Automatic Browser Refresh with Pelican

28 Nov 2016

LiveReload is a great (and free) tool for web development.

It can automatically refresh your browser based on file changes on your system. (html and css in this case) However, it requires multiple components (an addon, a server) and assumes that you know how the ruby ecosystem works. Hopefully this guide will help you overcome those hurdles.

Requirements

You will need to install the LiveReload browser addon available for Firefox or Chrome. The addon allows Guard::LiveReload to tell your browser to reload when files locally change on your system.

The required packages are ruby-bundler and ruby.

Install on Fedora 24

dnf install gen rubygem-bundler

Install on Archlinux

pacman -Syu ruby ruby-bundler

If ruby-bundler is not available from your package manager, you can install it as a gem (ruby-specific package) via gem install bundler. If you do choose to use gems, you may need to put a directory into your PATH.

Note

gem is ruby's package manager. It should come with your installation of ruby.

Now we have finished installing the dependencies' dependencies.

Guard and LiveReload

Guard and LiveReload are separate tools. LiveReload allows Guard to talk to the live-reload browser addon, and Guard monitors files on your filesystem for changes and can send notifications when it does.

To install Guard and LiveReload, create a file called Gemfile in the root of your pelican project. It is where and what dependencies you need for bundler.

Here's what Gemfile should contain:

source 'https://rubygems.org' do
  gem 'guard-livereload', '~> 2.5', require: false
  gem 'guard'
end

After you write the file. In the same directory run:

bundle install

Bundle will now install the Guard and LiveReload specified from the Gemfile. Now you can initialize guard:

bundle exec guard init

This will create a Guardfile in the current directory. The Guardfile is used to set what files are watched by Guard.

Notice since we installed guard through bundler we need the bundle exec.

Then we can run:

bundle exec livereload init

LiveReload will populate the Guardfile with is default parameters. However we are going to use our own configuration because the default options assume you are using LiveReload for a ruby-on-rails project.

My Guardfile looks like this:

guard 'livereload' do
  watch(%r{output/(.*/)*.*})
end

For a pelican project that's it. I look at any file in the output/ directory or its subdirectories (using a regular expression), and when any of those files change, Guard notifies LiveReload which notifies the browser addon, which reload the browser.

Once you have all this together you can run:

bundle exec guard

In the same directory as your Gemfile and Guardfile, which should be the root of your Pelican project.

Putting it all Together

Your directory should look like:

content/
develop_server.sh
output/
Gemfile
Guardfile
  • You have the Pelican development server running: ./develop_server.sh restart
  • You have guard started: bundle exec guard
  • Neither of them are giving you errors.

All you need to do now is go to your local web page on localhost:8000, enable the live-reload addon while on localhost (click the icon), and edit your themes or content with your favorite text editor. Once you save the file, the pelican server will regenerate the output/ directory. Then, Live-reload will notice the output directory has changed and will refresh your browser.

There you have it.

Note

Enable the live-reload addon icon by clicking it on the upper right-hand corner of your browser. You can check the status of the addon by hovering on its icon. It should look something like this.

livereload-tooltip

When you hover over the addon at localhost, you should see this tooltip

Pelican with sass

Although pelican has sass plugins, they didn't work for me for various reasons, so I used guard to compile my sass files into css files.

Further reading:

Comments !