Tags

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

{% 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, 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.