Refresh the browser when you save a file

Most of the pages on a Nesta site are written in a text editor, using Markdown or Textile. You don't get to see what your words look like on a web page until you save the file to disk and reload your browser. Wouldn't it be nice if your browser automatically reloaded pages as you saved them? When designing a theme, what if changes to HTML and CSS were reloaded immediately?

With the livereload and Guard projects, it's fairly easy to setup.

Note: Since I wrote this article, multiple new versions of livereload have been released. It looks as though that's an even easier way to reload your pages, but I haven't had a chance to try it with Nesta yet. These instructions are for Livereload 1.

Installing guard

Guard is distributed as a Ruby gem. We actually want the guard-livereload gem (which will pull in guard itself) so we'll add that to our Gemfile. We're going to add the rb-readline gem too, as it gives Guard a nice interactive prompt:

$ cat >> Gemfile
group :development do
  gem 'guard-livereload'
  gem 'rb-readline'
end

Now re-build your bundle to install the extra gems...

$ bundle

That's Guard installed.

Installing the browser plugin

Head over to the plugin instructions and download and install the browser plugin.

Setting up your Guardfile

Now we just need to create a Guardfile that will tell Guard what we want it to do. You can create the default config file like this:

$ guard init livereload

If you have a look at the Guardfile you'll see a few watch commands that specify paths to files that you'd find in a Rails app. Nesta keeps things in different places to Rails, so we'll be changing the contents of that file.

Mine looks like this:

$ cat > Guardfile
guard 'livereload' do
  watch(%r{content/pages(/.+)\.(mdown|textile|haml)}) { |match| match[1] }
  watch(%r{public(/.+\.(jpe?g|js|png))}) { |match| match[1] }
  watch(%r{views/.+\.haml})
  watch(%r{views/(.+)\.s[ac]ss}) do |match|
    if match[1] =~ /(mixins|variables)/
      ["/css/master.css", "/css/layout.css"]
    else
      "/css/#{match[1]}.css"
    end
  end
end

I won't go into too much detail about what's going on there; I think you'll do better by studying the code than you would at reading my attempt to explain it. The only thing I want to point out is that I usually have Sass files called views/mixins.sass and views/variables.sass. Those two files are never served to the browser; they're just included into master.sass and layout.sass. That's why when they change, Guard tells the browser to reload master.css and layout.css.

When you're happy with your config, run Guard like this:

$ guard

If you make some changes to Guardfile while guard is running you can prompt Guard to reload its config by typing "reload" at Guard's prompt.

Try it out

Run guard in one terminal window, and your local web server in another. Visit a web page, then right click in the browser window and select "Enable Livereload".

Any changes that you make to your content, HTML or CSS should now cause your browser to automatically reload.

If you want to see what else Guard can do, Ryan Bates has recorded a Railscast on Guard (livereload is introduced after 6 minutes and 20 seconds).

Graham Ashton is the author and maintainer of Nesta CMS. He lives in Manchester, in the UK.

He writes a technical blog at https://effectif.com and can be found at @gma@hachyderm.io on Mastodon.