README.md
# Guard::Haml
[](https://rubygems.org/gems/guard-haml) [](https://travis-ci.org/guard/guard-haml) [](https://gemnasium.com/guard/guard-haml) [](https://codeclimate.com/github/guard/guard-haml) [](https://codeclimate.com/github/guard/guard-haml)
Watches HAML files, compiles them to HTML on change.
* Compatible with HAML >= 3.
* Tested against Ruby 2.2.5, 2.3.1, Rubinius & JRuby (1.9 mode only).
## Install
Please be sure to have [Guard](https://github.com/guard/guard) installed before continuing.
Add Guard::Haml to your `Gemfile`:
```ruby
group :development do
gem 'guard-haml'
end
```
Add guard definition to your Guardfile by running this command:
```bash
$ 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:
```ruby
guard :haml, input: 'markup'
```
is equivalent to:
```ruby
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.:
```ruby
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:
```ruby
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.:
```ruby
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.
```ruby
"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:
```ruby
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.
```ruby
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`:
```ruby
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.:
```ruby
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](http://haml.info/docs/yardoc/file.HAML_REFERENCE.html#options) for more details.
### List of available options
``` ruby
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
helper_modules: [MyHelper] # List of modules be accessible by the HAML files during compilation, default: []
```
## Development
* Documentation hosted at [RubyDoc](http://rubydoc.info/gems/guard-haml/frames).
* Source hosted at [GitHub](https://github.com/guard/guard-haml).
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](https://travis-ci.org/guard/guard-haml).
* Update the [Yard](http://yardoc.org/) documentation.
* Update the [README](https://github.com/guard/guard-haml/blob/master/README.md).
* Please **do not change** the version number.
For questions please join us in our [Google group](http://groups.google.com/group/guard-dev) or on
`#guard` (irc.freenode.net).
## Author
[Immanuel Häussermann](https://github.com/manufaktor) ([@manufaktor](http://twitter.com/manufaktor), [manufaktor.com](http://manufaktor.com))
## Maintainer
[Rémy Coutable](https://github.com/rymai)
## Contributors
[https://github.com/guard/guard-haml/graphs/contributors](https://github.com/guard/guard-haml/graphs/contributors)