Guard::Haml

Watches HAML files, compiles them to HTML on change.

Compatible with HAML >= 3.
Tested against Ruby 1.9.3, 2.0.0, Rubinius & JRuby (1.9 mode only).

Install

Please be sure to have Guard installed before continuing.

Add Guard::Haml to your Gemfile:

group :development do
  gem 'guard-haml'
end

Add guard definition to your Guardfile by running this command:

$ guard init haml

Options

Configuring the input folder + automatic watchers generation

Use the :input option to define the folder where your HAML files are stored. This options also ensure the input folder won't be part of the output path.

If you set the :input option and don't define any watchers, Guard::Haml will automatically generates watchers with the pattern %r{^#{options[:input]}/(.+(\.html)?\.haml)$}. For instance:

guard :haml, input: 'markup'

is equivalent to:

guard :haml, input: 'markup' do
  watch %r{^markup/(.+(\.html)?\.haml)$}
end

Configuring the output destination

If you want to change the output directory use the :output option in your Guardfile, e.g.:

guard :haml, output: 'public' do
  watch %r{^src/.+(\.html\.haml)}
end

This output is relative to the Guardfile.

Multiple output option

This lets you compile to two (or more) html files from one haml file. This comes in handy if you want to compile to both a dev and prod build directory, for instance:

guard :haml, input: 'markup', output: ['public/dev', 'public/build'] do
  watch %r{^.+(\.haml)$}
end

If you maintain your haml files in a directory that should not be part of the output path, you can set the :input option, e.g.:

guard :haml, input: 'src', output: 'public' do
  watch %r{^src/.+(\.html\.haml)}
end

So when you edit a file src/partials/_partial.html.haml it will be saved to public/partials/_partial.html without the src.

File extensions

Guard::Haml will try to add the correct extension based on the input file name. You can provide multiple extensions to control the file name.

"foo.haml"     -> "foo.html"
"foo"          -> "foo.html"
"foo.txt"      -> "foo.txt.html"
"foo.php.haml" -> "foo.php"

You can override the default extension (html) using the :default_ext option:

guard :haml, default_ext: 'txt' do
  watch %r{^src/.+(\.html\.haml)}
end

Compile when starting guard

If you want to compile haml files when Guard starts you can use :run_at_start option.

guard :haml, output: 'public', input: 'src', run_at_start: true do
  watch %r{^src/.+(\.html\.haml)}
end

Guard notifications

You can disable Guard notifications by setting :notifications option to false:

guard 'haml', output: 'public', input: 'src', notifications: true do
  watch %r{^src/.+(\.html\.haml)}
end

Configuring HAML

If you want to pass options to the Haml engine, you can set the :haml_options option, e.g.:

guard :haml, output: 'public', input: 'src', haml_options: { ugly: true } do
  watch %r{^src/.+(\.html\.haml)}
end

This will produce compressed HTML. See Haml Reference for more details.

List of available options

input: 'markup'                        # define the folder where your HAML files are stored
output: ['public/dev', 'public/build'] # define the output folder where conpiled HAML files are saved
default_ext: 'txt'                     # override the default extension (`html`)
run_at_start: false                    # compile haml files when Guard starts, default: false
notifications: false                   # enable/disable Guard notifications, default: true
haml_options: { ugly: true }           # HAML options (passed directly to HAML), default: {}
auto_append_file_ext: false            # automatically append `.html` to the generated files, default: true

Development

Documentation hosted at RubyDoc.
Source hosted at GitHub.

Pull requests are very welcome! Please try to follow these simple rules if applicable:

Please create a topic branch for every separate change you make.
Make sure your patches are well tested. All specs must pass on Travis CI.
Update the Yard documentation.
Update the README.
Please do not change the version number.

For questions please join us in our Google group or on #guard (irc.freenode.net).

Author

Immanuel Häussermann (@manufaktor, manufaktor.com)

Maintainer

Rémy Coutable

Contributors

https://github.com/guard/guard-haml/graphs/contributors

einarj/guard-haml