Skip to main content
Documentation Configuration Plugins


It’s easy to add new Liquid tags (sometimes called “shortcodes”) to your site. Tags provide extra functionality you can use inside of your Markdown content and any HTML template. Built-in examples added by Bridgetown include the post_url and asset_path tags. Below is an example of a custom Liquid tag that will output the time the page was rendered:

class RenderTime < SiteBuilder
  def build
    liquid_tag :render_time do |attributes|
      "#{attributes} #{}"

In the example above, we can place the following tag anywhere in one of our pages:

<p>{% render_time page rendered at: %}</p>

And we would get something like this on the page:

<p>page rendered at: Tue June 22 23:38:47 –0500 2010</p>

Tag Blocks #

The render_time tag seen above can also be rewritten as a tag block. Look at this example:

class RenderTime < SiteBuilder
  def build
    liquid_tag :render_time, as_block: true do |attributes, tag|
      "#{tag.content} #{}"

We can now use the tag block anywhere:

{% render_time %}
page rendered at:
{% endrender_time %}

And we would still get the same output as above on the page:

<p>page rendered at: Tue June 22 23:38:47 –0500 2010</p>

In the above example, the tag block and the tag are both registered with the name render_time, but you’ll want to avoid registering a tag and a tag block using the same name in the same project as this will lead to conflicts.

Using Instance Methods #

As with other parts of the Builder API, you can also use an instance method to register your tag:

class Upcase < SiteBuilder
  def build
    liquid_tag :upcase, :upcase_tag, as_block: true

  def upcase_tag(attributes, tag)

If your tag name and method name are the same, you can omit the second argument.

{% upcase %}
i am upper case
{% endupcase %}


Supporting Multiple Attributes and Accessing Template Variables #

If you’d like your tag to support multiple attributes separated by a comma, that’s easy to do with the following statement:

param1, param2 = attributes.split(",").map(&:strip)

Then you could use the tag like this:

{% mytag value1, value2 %}

You can also access local Liquid template variables from within your tag by accessing the context object, and that includes nested variables you would normally access such as {{ page.title }}.

Given a page with a title “My Exciting Webpage”, you could reference it like this:

tag.context["page"]["title"] # returns "My Exciting Webpage"

When to use a Tag vs. a Filter #

Tags and Tag Blocks are great when you simply want to insert a customized piece of content/HTML code into a page. If instead you want to transform input data from one format to another and potentially allow multiple transformations to be chained together, then it’s probably better to write a Filter.

If you prefer to use the Legacy API (aka Liquid::Template.register_tag) to construct Liquid tags, refer to the Liquid documentation here.

Back to Plugins