Filters

The following is a list of Nanoc filters. Most of these are bundled with Nanoc; for those that are not, installation instructions are provided.

`:asciidoc`

The :asciidoc filter invokes the command-line tool of AsciiDoc. This filter takes no options.

For example, the following will convert an AsciiDoc page to HTML:

filter :asciidoc

`:asciidoctor`

The :asciidoctor filter invokes Asciidoctor, a Ruby implementation of AsciiDoc. Unlike the :asciidoc filter, the :asciidoctor filter can be customized.

For example, the following will convert an AsciiDoc page to HTML:

filter :asciidoctor

`:bluecloth`

The :bluecloth filter invokes BlueCloth, a pure-Ruby implementation of Markdown. This filter takes no options.

For example, the following will convert a Markdown page to HTML:

filter :bluecloth

`:coffeescript`

The :coffeescript filter runs the content through CoffeeScript. This filter takes no options.

For example, the following will convert CoffeeScript source code into JavaScript:

filter :coffeescript

`:colorize_syntax`

The :colorize_syntax filter finds code blocks and attempts to syntax-highlight them.

Code blocks are code elements wrapped in a pre element. The language of the code can be specified in two ways:

as an attribute

If the code element has an HTML class attribute that starts with language-, then the remainder of the class attribute will be used as the code language. For example, the following indicates a code block written in Ruby:

<pre><code class="language-ruby">puts "Hello world!"</code></pre>

as a code comment

If the code block starts with a line that begins with #!, then the remainder of the line will be used as the code language. For example, the following indicates a code block written in JSON:

<pre><code>#!json
{"greeting":"Hello, world!"}
</code></pre>

By default, CodeRay will be used to highlight source code. For example, the following will colorize the syntax of all code blocks using CodeRay:

filter :colorize_syntax

To change the colorizer, pass a symbol containing the name of a colorizer to :default_colorizer. For example, the following highlights all code blocks using Rouge:

filter :colorize_syntax, default_colorizer: :rouge

Nanoc knows the following colorizers:

:coderay: CodeRay, a Ruby syntax highlighter
:pygmentize: pygmentize, the command-line front end for Pygments, a syntax highlighter written in Python
:pygmentsrb: pygments.rb, a fast Ruby interface for Pygments
:simon_highlight: Highlight, by Andre Simon
:rouge: Rouge, a pure-Ruby syntax highlighter with Pygments-compatible output

To configure individual highlighters, pass the options to the key for the highlighter. For example, the following will set the line_numbers option to :table for CodeRay:

filter :colorize_syntax, coderay: { line_numbers: :table }

Syntax colorizers can be configured on a per-language basis. To do so, use a :colorizers option, passing in a hash where the keys are symbols corresponding to language names, and where the values are symbols corresponding to colorizer names. For example, in the following code snippet, Rouge would be used by default, except for XML, where it uses CodeRay:

filter :colorize_syntax,
  default_colorizer: :rouge,
  colorizers: { xml: :coderay }

The colorize_syntax filter by default assumes that the content to colorize is an HTML page fragment, rather than a full HTML page, and will therefore not add the HTML boilerplate at the top and bottom of the output. To rather treat the content as a full page, pass is_fullpage: true to the filter. Typically, the is_fullpage: true option is useful when the content is already fully laid out.

The syntax of the document to highlight is assumed to be HTML by default. To parse the document as HTML5 instead, pass syntax: :html5 to the filter() function. XHTML and XML are also available.

If you want to highlight code elements even when they are not contained inside a pre element, pass outside_pre: true.

`:dart_sass`

The :dart_sass filter runs the content through Sass. Options passed to this filter will be passed on to Dart Sass.

For example, the following will convert Sass with SCSS syntax into CSS:

filter :dart_sass, syntax: 'scss'

The :dart_sass filter is not bundled with Nanoc. To install it, add the nanoc-dart-sass gem to the nanoc group of your Gemfile:

group :nanoc do
  gem 'nanoc-dart-sass'
end

`:erb`

The :erb filter runs the content through eRuby, using the ERB class.

For example, the following will process ERB source code:

filter :erb

The following example contains ERB code that iterates over all blog posts, and prints them as a header and an excerpt of the body:

<% @items.find_all('/blog/*').each do |post| %>
  <h2><%= post[:title] %></h2>
  <p><%= excerpt(post.compiled_content(snapshot: :pre)) %></p>
<% end %>

ERB supports the following syntax:

<% statement %>: Evaluates statement, and discards the result.
<%= expression %>: Evaluates expression, and substitutes the ERB instruction with the result of the expression.

Options

The :erb filter takes the following options:

:safe_level

The safe level ($SAFE) to use while running this filter. By default, this is 0, which means no taint checks are performed.

:trim_mode

The trim mode to use, which changes the way ERB interprets its source. The ERB documentation lists the following trim modes:

"%": enables Ruby code processing for lines beginning with %
"<>": omit newline for lines starting with <% and ending in %>
">": omit newline for lines ending in %>
"-": omit blank lines ending in -%>

For example, with trim_mode: '%', the initial ERB example above could be written as follows:

% @items.find_all('/blog/*').each do |post|
  <h2><%= post[:title] %></h2>
  <p><%= excerpt(post.compiled_content(snapshot: :pre)) %></p>
% end

For this to work, the :erb filter would have to be called with the proper trim mode set:

filter :erb, trim_mode: '%'

`:erubi`

The :erubi filter runs the content through eRuby, using Erubi. Options passed to this filter will be passed on to Erubi::Engine.new.

For example, the following will process eRuby source code using Erubi:

filter :erubi

`:erubis`

The :erubis filter runs the content through eRuby, using Erubis. This filter takes no options.

For example, the following will process eRuby source code using Erubis:

filter :erubis

`:external`

The :external filter runs the content through an external program.

For example, the following will run content through a htmlcompressor executable:

filter :external, exec: '/opt/local/bin/htmlcompressor'

The external command must receive input from standard input (“stdin”) and must send its output to standard out (“stdout”).

Options passed to this filter will be passed on to the external command. For example:

filter :external,
  exec: 'multimarkdown',
  options: ['--accept', '--mask', '--labels', '--smart']

The :external filter is not bundled with Nanoc. To install it, add the nanoc-external gem to the nanoc group of your Gemfile:

group :nanoc do
  gem 'nanoc-external'
end

`:haml`

The :haml filter runs the content through Haml.

For example, the following will convert Haml into HTML:

filter :haml

The options that are given to this filter will be passed on to Haml::Engine#initialize. For example, this filter call set :format to :html5:

filter :haml, format: :html5

`:handlebars`

The :handlebars filter processes Handlebars code using handlebars.rb.

For example, the following will convert Handlebars content into HTML:

filter :handlebars

Content that is processed using the Handlebars filter can access the following data:

item.attr
attr: Returns the item attribute with the given name. For example, {{ item.title }} and {{ title }} in Handlebars are both evaluated as <%= item[:title] %> in ERB.
layout.attr: Returns the layout attribute with the given name. This is only available in layouts. For example, {{ layout.title }} in Handlebars is evaluated as <%= layout[:title] %> in ERB.
config.attr: Returns the configuration attribute with the given name.
yield: Returns the content to be included in the layout. This is only available in layouts.

For example, this is a basic layout marked up with Handlebars:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>{{ config.site_title }}: {{ item.title }}</title>
  </head>
  <body>
    <h1>{{ item.title }}</h1>
    {{{ yield }}}
  </body>
</html>

This filter does not have any options.

`:kramdown`

The :kramdown filter invokes kramdown, a fast and featureful pure-Ruby implementation of Markdown. The filter converts to HTML.

For example, the following will convert a Markdown page to HTML:

filter :kramdown

Parameters that are passed to the filter are passed to Kramdown::Document.new. For example, the following will also convert the content to HTML, as above, but disables the auto_ids option:

filter :kramdown, auto_ids: false

For a list of all options for kramdown, see kramdown’s options reference page.

`:less`

The :less filter runs content through Less, a CSS preprocessor.

For example, the following will process Less content:

filter :less

This filter does not have any options.

`:markaby`

The :markaby filter runs content through Markaby, a method of writing markup as Ruby.

For example, the following will process Markaby content:

filter :markaby

This filter does not have any options.

`:maruku`

The :maruku filter runs content through Maruku, a pure-Ruby Markdown-superset interpreter.

For example, the following will process Markdown content using Maruku:

filter :maruku

The options that are passed to this filter will be passed on to Maruku’s Maruku.new method.

`:mustache`

The :mustache filter runs content through Mustache.

For example, the following will convert Mustache content into HTML:

filter :mustache

Content that is processed using the Handlebars filter can access the following data:

attr: Returns the item attribute with the given name. For example, {{ title }} in Handlebars is evaluated as <%= item[:title] %> in ERB.
yield: Returns the content to be included in the layout. This is only available in layouts.

For example, this is a basic layout marked up with Mustache:

<!DOCTYPE html>
<html>
  <head>
    <meta charset="utf-8">
    <title>{{ title }}</title>
  </head>
  <body>
    <h1>{{ title }}</h1>
    {{{ yield }}}
  </body>
</html>

This filter does not have any options.

`:org_mode`

The :org_mode filter runs the content through Org Mode. For example:

filter :org_mode

This filter takes no options.

The :org_mode filter is not bundled with Nanoc. To install it, add the nanoc-org-mode gem to the nanoc group of your Gemfile:

group :nanoc do
  gem 'nanoc-org-mode'
end

`:pandoc`

The :pandoc filter runs content through Pandoc using PandocRuby.

For example, the following will convert Pandoc content into HTML:

filter :pandoc

To pass options to :pandoc filter, pass them as an array for the :args key. For example, the following will convert from Markdown to HTML, and enable the --no-wrap and --table-of-contents options:

filter :pandoc, args: [
  { from: :markdown, to: :html },
  'no-wrap',
  :table_of_contents,
]

For backwards compatibility, it is also possible to pass options directly as a hash to the :pandoc filter. For example:

filter :pandoc, from: :markdown, to: :html

This approach is less flexible, however, as it is not capable of passing options without values, such as the --no-wrap and --table-of-contents options in the example above.

`:rainpress`

The :rainpress filter runs CSS through Rainpress, a CSS compressor.

For example, the following will compress CSS with Rainpress:

filter :rainpress

Options passed to this filter will be passed to Rainpress. See the rainpress.rb file for a description of the options. For example, the following will retain newlines:

filter :rainpress, newlines: false

`:rdiscount`

The :rdiscount filter runs content through RDiscount, a Ruby interface to Discount.

For example, the following will convert Markdown content into HTML using RDiscount:

filter :rdiscount

Options can be passed as an array of symbols for the :extension key. For example, the following will convert from Markdown to HTML, and enable the :smart and :filter_html options:

filter :rdiscount, extensions: [:smart, :filter_html]

`:rdoc`

The :rdoc filter runs content through RDoc::Markup.

For example, the following will convert RDoc content into HTML:

filter :rdoc

This filter takes no options.

`:redcarpet`

The :redcarpet filter runs content through Redcarpet.

For example, the following will convert Markdown content into HTML via Redcarpet:

filter :redcarpet

This filter takes the following options:

:options: A list of options to pass on to Redcarpet itself (not the renderer)
:renderer_options: A list of options to pass on to the Redcarpet renderer
:renderer: The class of the renderer to use (Redcarpet::Render::HTML by default)
:with_toc: Whether or not to add a table of contents

For example, the following will enable fenced code blocks:

filter :redcarpet, options: { fenced_code_blocks: true }

`:redcloth`

The :redcloth filter runs content through RedCloth, a Ruby implementation of Textile.

For example, the following will convert Textile content into HTML via RedCloth:

filter :redcloth

This filter takes the following options:

:filter_class
:filter_html
:filter_ids
:filter_style
:hard_breaks
:lite_mode
:no_span_caps
:sanitize_html

Set the value for the option key to true or false to enable or disable the option. For details, see the documentation for RedCloth::TextileDoc.

For example, the following disable wrapping caps in a span:

filter :redcloth, no_span_caps: true

`:relativize_paths`

The :relativize_paths filter finds all absolute paths in (X)HTML or CSS content, and converts them into relative paths. This is particularly useful for sites that are not deployed at the root of a domain.

For example, the GitHub Pages site for D★Mark is hosted at https://ddfreyne.github.io/d-mark/. The D★Mark page has a reference to its stylesheet at /assets/style.css, which the :relativize_paths filter turns into assets/style.css, so that the stylesheet can be found even if the site is not deployed at the root of the domain.

The :type option specifies the type of content, and can be :html5, :html, :xhtml, :xml, or :css. This option must be specified, as the filter cannot reliably determine the type of content by itself.

For example, the following will convert all absolute paths in HTML content to relative ones:

filter :relativize_paths, type: :html5

In HTML, all href and src attributes will be relativized. In CSS, all url() references will be relativized.

To customize which attributes to normalize in (X)HTML, pass a list of XPath selectors to the :select option. Selectors are prefixed with descendant-or-self:: automatically. For example, the following will only relativize paths if they occur within href attributes on any element anywhere in the document:

filter :relativize_paths, type: :html5, select: ['*/@href']

If custom namespaces in XHTML are passed to the :select option, they also have to be explicitly defined in the :namespaces option. The :namespaces option is a hash where the keys are the prefixes, and the values are the namespace URIs.

To exclude paths from being relativized, use the :exclude option. The value of the :exclude option can be any of the following:

Regexp (regular expression): The path will not be relativized if the regular expression matches.
String: The path will not be relativized when the path starts with one or more components that matches the given string.
Array of Regexp or String: The path will not be relativized if any of the elements of the array match, using the aforementioned rules for Regexp and String.

For example, the following will prevent all paths to /cgi-bin from being relativized:

filter :relativize_paths, type: :html5, exclude: '/cgi-bin'

`:rubypants`

The :rubypants filter transforms content using RubyPants, which translates plain ASCII punctuation characters into “smart” typographic punctuation HTML entities.

The following will run RubyPants:

filter :rubypants

This filter takes no options.

`:sass`

The :sass filter converts a Sass stylesheet to CSS. For example:

filter :sass

This filter uses the Ruby Sass implementation, which has reached end of life. Consider using the more modern :dart_sass filter instead.

The options that are given to this filter will be passed on to Sass::Engine#initialize, to the exception of the sourcemap_path option. For example, this filter call set :style to :compact:

filter :sass, style: :compact

You can evaluate Ruby code from within your Sass code using the nanoc() Sass function. It takes a string containing Ruby code (a Sass::Script::Value::String):

/* This is the input Sass code */
.title {
  content: nanoc('@config[:title]');
}

# nanoc.yaml
title: "My wonderful web site"

/* This is the resulting CSS */
.title {
  content: "My wonderful web site";
}

The nanoc() Sass function can also take an $unquote parameter, which removes quotation marks:

/* This is the input Sass code */
.tip {
  color: nanoc('@config[:tip_color]', $unquote: true);
}

# nanoc.yaml
tip_color: '#990099'

/* This is the resulting CSS */
.tip {
  color: #990099;
}

`:sass_sourcemap`

The :sass_sourcemap filter produces a source map for a rendered Sass stylesheet. For example:

path = @item.identifier.without_ext + '.css'
filter :sass_sourcemap, css_path: path, sourcemap_path: path + '.map'

Both :sass and :sass_sourcemap filters must be passed the same options.

`:slim`

The :slim filter runs the content through Slim, a lightweight templating engine. For example:

filter :slim

Options passed to this filter will be passed to Slim::Template#initialize.

`:tilt`

The :tilt filter runs the content through Tilt. For example:

filter :tilt

Options passed to this filter will be passed on to the filter. For example:

filter :tilt, args: { escape: true }

The :tilt filter is not bundled with Nanoc. To install it, add the nanoc-tilt gem to the nanoc group of your Gemfile:

group :nanoc do
  gem 'nanoc-tilt'
end

`:typogruby`

The :typogruby filter runs the content through Typogruby, a Ruby variant of Typogrify for typographically enhancing text. For example:

filter :typogruby

This filter takes no options.

`:uglify_js`

The :uglify_js filter passes JavaScript content through Uglifier, a Ruby wrapper for UglifyJS. For example:

filter :uglify_js

This filter takes options and passes them on to Uglifier#initialize. For example, the following will disable name mangling and enable support for Harmony mode (ES6/ES2015+):

filter :uglify_js, mangle: false, harmony: true

`:xsl`

The :xsl filter runs the item content through an XSLT stylesheet using Nokogiri.

This filter can only be run for layouts, because it will need both the XML to convert (the item content) as well as the XSLT stylesheet (the layout content).

For example, the following specifies that items matching /reports/* will be laid out with the /xsl-report.* layout, which is defined to be filtered with XSL:

compile '/reports/*' do
  layout '/xsl-report.*'
end

layout '/xsl-report.*', :xsl

Additional parameters can be passed to the layout call. These parameters will be turned into xsl:param elements. For example, the following layout rule adds an additional parameter named vat, set to 21.5:

layout '/xsl-report.*', :xsl, vat: '21.5'

`:yui_compressor`

The :yui_compressor filter compresses JavaScript or CSS using the YUICompressor gem.

For example, the following compresses CSS content:

filter :yui_compressor, type: 'css'

At least the :type option must be specified. The :type option can be set to either 'css' or 'js', corresponding with CSS and JavaScript.

This filter takes options and passes them on to YUICompressor.compress. For details on which options are available, consult the YUICompressor.compress documentation. For example, the following will enable name munging in JavaScript:

filter :yui_compressor, type: 'js', munge: true