Using common filters

This guide gives an overview of typical approaches for using common filters.

Using Sass

Sass is a CSS extension language that supports variables, mixins, partials, and more. To use Sass with Nanoc, create a rule that matches /**/*.sass, calls the :sass filter, and writes out a .css file:

compile '/**/*.sass' do
  filter :sass
  write @item.identifier.without_ext + '.css'
end

If you prefer using the SCSS syntax for Sass, rather than the default Sass syntax, pass syntax: :scss to the :sass filter, and match on /**/*.scss rather than /**/*.sass:

compile '/**/*.scss' do
  filter :sass, syntax: :scss
  write @item.identifier.without_ext + '.css'
end

For more information, see the :sass filter reference.

Support Sass and SCSS

Sass has two syntaxes: Sass and SCSS. To support both, you can use curly braces in a compilation rule’s pattern to match both extensions:

compile '/css/*.{sass,scss}' do
  syntax = @item.identifier.ext.to_sym
  filter :sass, syntax: syntax, style: :compact
end

The :sass filter is passed the :syntax option, which in the example above is derived from the item’s identifier.

Using partials

Partials are Sass files that don’t have an output file, but only serve to be included in another Sass file. By convention, filenames of partials start with an underscore (e.g. css/_layout.scss), which makes it possible for them to be handled specially within Nanoc:

ignore '/css/_*.sass'

compile '/css/*.sass' do
  filter :sass, syntax: :sass, style: :compact
end

With the rules defined above, you will be able to import Sass partials:

@import "/css/**/_layout.*"

Using Sass source maps

Nanoc’s Sass filter supports source maps, which makes debugging Sass easier. To generate a source map for Sass, use the :sass_sourcemap filter:

[:default, :sourcemap].each do |rep_name|
  compile '/css/**/*.sass', rep: rep_name do
    path = @item.identifier.without_ext + '.css'
    options = { syntax: :sass, style: :compact, css_path: path, sourcemap_path: path + '.map' }

    case rep_name
    when :default
      filter :sass, options
      write path
    when :sourcemap
      filter :sass_sourcemap, options
      write path + '.map'
    end
  end
end

When using the :sass_sourcemap filter, be sure to invoke it with the same options as the :sass filter.

The :sass filter also supports generating inline source maps:

compile '/css/**/*.scss'
  path = @item.identifier.without_ext + '.css'
  options = { syntax: :sass, style: :compact, css_path: path, sourcemap_path: :inline }

  filter :sass, options
end

Using nanoc() in Sass

Nanoc’s Sass filter defines a nanoc() Sass function, which allows you to evaluate Ruby code from Sass within the compilation context. It takes a string containing Ruby code.

For example, assume a configuration file (nanoc.yaml) with the following contents:

auto_number_headings: true

The Sass file can now reference the title defined in the configuration:

@if nanoc('@config[:auto_number_headings]') {
  body { counter-reset: h2; }
  h2 { counter-reset: h3; }

  h2:before { counter-increment: h2; content: counter(h2) ". "; }
  h3:before { counter-increment: h3; content: counter(h2) "." counter(h3) ". "; }
}

The resulting CSS will set up auto-numbering of headings (h2 and h3) if the configuration has auto_number_headings set to true.

Using kramdown

kramdown is a fast and featureful Markdown processor. To use it with Nanoc, create a rule that matches /**/*.md and calls the :kramdown filter:

compile '/**/*.md' do
  filter :kramdown
  layout '/default.*'
  write item.identifier.without_ext + '.html'
end

The :kramdown filter can take options. For example, pass auto_ids: false to disable automatic header ID generation:

compile '/**/*.md' do
  filter :kramdown, auto_ids: false
  layout '/default.*'
  write item.identifier.without_ext + '.html'
end

For more information, see the :kramdown filter reference.