⛓️Filters

Filters let another program process the text inside them. You could, for example, write Sass or SCSS in your template and use a filter to compile it to regular CSS to be included when the template is rendered.

Filters are implemented through commands just as you would run them in a terminal. The content of the filter is given to the command through stdin and it's unescaped stdout is put in the template.

Filters are processed during compile time. Hence, you cannot use interpolation in them and you won't need to escape any #.

You can also give space-separated arguments to the command. Just like in the shell, you may enclose arguments in strings which will be parsed like regular Go strings using strconv.Unquote.

Executing arbitrary commands poses a security risk (Imagine someone used rm -rf --no-preserve-root / as a filter).

While you should of course always vet what go generate executes, it is always better to be safe than sorry. Hence, corgi will only run filters previously approved.

You can approve a filter by specifying it in the -trusted-filter flag.

On Linux, macOS, and Windows, you can also use corgi -edit-trusted-filters to start an editor to edit a list of user-wide trusted filters, or directly open $HOME/.config/corgi/trusted_filters or %AppData%\Local\corgi\trusted_filters.

If you trust the template you are running (or just don't care if someone steals your bank details ;)), you can set the -trust-all-filters flag to i know this is dangerous to allow all filters to be run.

Corgi

style
  //- https://sass-lang.com
  :sass --stdin
    nav
      ul
        margin: 0
        padding: 0
        list-style: none

      li
        display: inline-block

HTML

<style>


  nav ul {
    margin: 0;
    padding: 0;
    list-style: none;
  }
  
  nav li {
    display: inline-block;
  }
</style>

The Built-In Raw Filter

If you don't specify any command, corgi will write the contents verbatim to the document. This is useful, if you want to include an HTML snippet like an svg, without the hassle of converting it to corgi-syntax.

It is equivalent to using :tee, except that it doesn't require tee to be installed on the system.

You don't need to approve the raw filter, it is always available.

Corgi

p Look at my cool icon:
p
  :raw 
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
      <path d="M 5 5 L 5 6.3398438 L 15 19.339844 L 15 26 L 10 26 L 10 28 L 22 28 L 22 26 L 17 26 L 17 19.339844 L 27 6.3398438 L 27 5 L 5 5 z M 8.03125 7 L 23.96875 7 L 22.429688 9 L 11.919922 9 L 13.458984 11 L 20.892578 11 L 16 17.359375 L 8.03125 7 z"/>
    </svg>

HTML

<p>Look at my cool icon:</p>
<p>

    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
      <path d="M 5 5 L 5 6.3398438 L 15 19.339844 L 15 26 L 10 26 L 10 28 L 22 28 L 22 26 L 17 26 L 17 19.339844 L 27 6.3398438 L 27 5 L 5 5 z M 8.03125 7 L 23.96875 7 L 22.429688 9 L 11.919922 9 L 13.458984 11 L 20.892578 11 L 16 17.359375 L 8.03125 7 z"/>
    </svg>
</p>

Minification

The Raw Filter can also minify HTML, SVGs, JavaScript, and CSS. Simply write html, svg, js, or css behind the filter to enable it.

Corgi

p
  :raw svg
    <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
      <path d="M 5 5 L 5 6.3398438 L 15 19.339844 L 15 26 L 10 26 L 10 28 L 22 28 L 22 26 L 17 26 L 17 19.339844 L 27 6.3398438 L 27 5 L 5 5 z M 8.03125 7 L 23.96875 7 L 22.429688 9 L 11.919922 9 L 13.458984 11 L 20.892578 11 L 16 17.359375 L 8.03125 7 z"/>
    </svg>

HTML

<p><svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32"><path d="M5 5V6.3398438L15 19.339844V26H10v2H22V26H17V19.339844L27 6.3398438V5H5zM8.03125 7h15.9375L22.429688 9H11.919922L13.458984 11H20.892578L16 17.359375 8.03125 7z"/></svg></p>