Filters

To pass options to the filter, add them inside parentheses after the filter name (just as you would do with tag attributes): .

All can be used as Pug filters. Popular filters include :babel, :uglify-js, :scss, and :markdown-it. Check out the documentation for the JSTransformer for the options supported for the specific filter.

If you can’t find an appropriate filter for your use case, you can write your own custom filter.

For example, if you want to be able to use CoffeeScript and Markdown (using Markdown-it renderer) in your Pug template, you would first make sure that these features are installed:

  1. :markdown-it(linkify langPrefix='highlight-')
  2.   # Markdown
  4.   Markdown document with http://links.com and
  6.   ```js
  7.   var codeBlocks;
  8.   ```
  9.   :coffee-script
  1. <h1>Markdown</h1>
  2. <p>Markdown document with <a href="http://links.com">http://links.com</a> and</p>
  3. <pre><code class="highlight-js">var codeBlocks;
  4. </code></pre>
  5. <script>
  6.   (function() {
  7.     console.log('This is coffee script');
  9.   }).call(this);
  10. </script>
Warning

Filters are rendered at compile time. This makes them fast, but it also means that they cannot support dynamic content or options.

By default, compilation in the browser does not have access to JSTransformer-based filters, unless the JSTransformer modules are explicitly packed and made available through a CommonJS platform (such as Browserify or Webpack). In fact, the page you are reading right now uses Browserify to make the filters available in the browser.

Templates pre-compiled on the server do not have this limitation.

If the content of the filter is short, one can even use filters as if they are tags:

  1. <p><strong>BOLD TEXT</strong></p>
  2. </p>

You can apply multiple filters on the same block of text. To do so, simply specify the filters on the same line.

The filters are applied in reverse order. The text is first passed to the last filter; then, the result is passed to the second last filter, and so on.

In the following example, the script is first transformed by babel, and then by .

  1. script
  2.   :cdata-js:babel(presets=['es2015'])
  3.     const myFunc = () => `This is ES2015 in a CD${'ATA'}`;

You can add your own filters to Pug via the filters option.

  1. options.filters = {
  2.   'my-own-filter': function (text, options) {
  3.     if (options.addStart) text = 'Start\n' + text;
  4.     if (options.addEnd)   text = text + '\nEnd';
  5.     return text;
  6.   }
  7. };
  1. p
  2.   :my-own-filter(addStart addEnd)