Twig Tags

Grav also provides a variety of custom Twig Tags that extend the already very capable Twig templating capabilities with some new tags that we've found useful.


The Markdown tag provides a powerful new way to embedding markdown in Twig template. You could use a variable and render that variable with the |markdown filter, but the {% markdown %} syntax makes creating blocks of markdown text even simpler.

{% markdown %}
This is **bold** and this _underlined_

1. This is a bullet list
2. This is another item in that same list
{% endmarkdown %}


The Scripts tag is really a convenience tag that keeps your Twig more readable compared to the usual {% do assets...%} approach. It's purely an alternative way of writing things.


{% script 'theme://js/something.js' in 'bottom' priority: 20 with { defer: true, async: true } %}


{% script in 'bottom' priority: 20 %}
{% endscript %}

CSS Styles


{% style 'theme://css/foo.css' priority: 20 %}


{% style priority: 20 with { media: 'screen' } %}
    a { color: red; }
{% endstyle %}


In most programming language, using a switch statement is a common way to make a bunch of is else statements cleaner and more readabile. Also they may prove to be marginally faster. We just provide a simple way of creating these as they were missing in the base Twig functionality.

{% switch type %}
  {% case 'foo' %}
     {{ }}
  {% case 'bar' %}
     {{ }}
  {% default %}
     {{ my_data.default }}
{% endswitch %}

Deferred Blocks

A great new feature of Grav 1.6 is the power of deferred blocks. With traditional blocks, once the block has been rendered, it cannot be manipulated. Take the example of a {% block scripts %} that might hold some entries for JavaScript includes. If you have a child Twig template, and you extend a base template where this block is defined, you can extend the block, and add your own custom JavaScript entries. however, partial twig templates that are included from this page, cannot reach or interact with the block.

The deferred attribute on the block which is powered by the Deferred Extension, means that you can define this block in any Twig template, but it's rendering is deferred, so that it renders after everything else. This means that you can add JavaScript references via the {% do assets.addJs() %} call from anywhere in your page, and because the rendering is deferred, the output will contain all the assets that Grav knows about, no matter when you added them.

{% block myblock deferred %}
    This will be rendered after everything else. 
{% endblock %}

Found errors? Think you can improve this documentation? Simply click the Edit link at the top of the page, and then the icon on Github to make your changes.