Tags

Liquid tags (sometimes called “shortcodes”) 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} #{Time.now}"
    end
  end
end

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} #{Time.now}"
    end
  end
end

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>

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
  end

  def upcase_tag(attributes, tag)
    tag.content.upcase
  end
end

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

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

output: I AM UPPER CASE

Supporting Multiple Attributes and Accessing Template Variables #

If you’d like your tag to support multiple attributes separated by a comma:

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 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.

Back to Plugins