Filters

You can read about the filters available for Jekyll or the base Liquid. To simplify working with the website and to avoid manual loops in liquid, we also provide the following filters:

General filters

These are not specific to IRIS-HEP’s design.

basename

This gives you the basename from the file. You can optionally give an argument; unlike Ruby, ".*" is the default.

{{ "/my/file.txt" | basename }} -> "file"
{{ "/my/file.txt" | basename: ""}} -> "file.txt"

keys / values

For a hash (dict in Python), these filters pull out the array of keys or values.

{{ site.data.people | keys }} -> ["person1", "person2", ...]
{{ site.data.people | values }} -> [{"name: "Person 1", ...]

ensure_array / ensure_arrays

For an object, make sure it is an array. Anything other than an array becomes a length-one array, with the exception of nil, which becomes an empty array. This is useful for allowing a string or a list in a yaml file. ensure_arrays does the same thing for an array of items that should be an array of arrays.

{{ nil | ensure_array }} -> []
{{ "hi" | ensure_array }} -> ["hi"]

flat_map

For an array of arrays, this flattens it to a single array.

{{ nested_array | flat_map }} -> ["a1", "a2", "b1", ...]

where_overlap

This will return the overlapping items between an array of hashes (dicts) and an array (treating them as unordered sets). You give it a key to compare on.

{{ dict | where_overlap: "key", other_array }}

where_day_range / where_month_range

These select objects with dates from a range of values. You can specify the start and end day (or month), in time before today. If you leave of the stop (nil), it is endless. You specify the key to look up the date on.

{{ object_array | where_day_range: "eventdate", 10, 0 }} -> Select events during the last 10 days
{{ object_array | where_day_range: "eventdate", 0 }} -> Select upcoming events
{{ object_array | where_month_range: "eventdate", 3, 1 }} -> Select events from 1-3 months ago.

select / reject

This selects or rejects were something is truthy (not nil or false). It acts like what I think a one-argument form of “where” should have acted like. In the two-argument form, this acts like normal where, but allows nested lookups and rejection. Also consider where_exp.

{{ object_array | select: "active" }} -> Select items where active is not nil (missing) or False
{{ object_array | reject: "active" }} -> Select items where active is nil (missing) or False

puts

This does nothing, but prints out the contents to the screen when compiling. Only useful for debugging.

{{ "Hello logs!" | puts }}

hash_fetch

This will fetch items from a hash (dict) using an array, returning the value if the key is in the hash, and nil for array items that are not keys in the hash. If you have a nested key, you can pass that as an option.

{{ key_array | hash_fetch: hash }} -> value_array
{{ key_hash_array | hash_fetch: hash, "id" }} -> value_array

last_name_sort

This sorts an array of hashes that include normal ordered names in a key by by last name.

{{ people | last_name_sort: "name" }} -> {"name": "Zee Alpha", ...

nested_sort

This performs a nested sort. It works on Pages or on hashes. It also is stable, so you can sort by something else first.

{{ site.pages | nested_sort: "date.start" }} -> Sort by a date nested into a structure

IRIS-HEP specific filters

There are also some filters specific to IRIS-HEP.

print_date_range / print_date_range_month

You can pretty-print a range of dates at the day level or month level.

{{ start_date | print_date_range: stop_date }} -> start day - stop day
{{ start_date | print_date_range_month: stop_date }} -> start month - stop month

smart_title_sort

This sorts pages by “title”, also taking into account “position”, if it exists.

{{ site.pages | smart_title_sort }} -> Sorted pages

iris_hep_fellows_sort

This sorts fellows pages by starting date stably. Suggested usage:

{{ site.pages | where: "pagetype", "fellow" | last_name_sort: "fellow-name" | reverse | iris_hep_fellow_sort | reverse }} -> Sorted fellow pages

Tags / Blocks

General tags / blocks

raise_error (tag)

This will raise an error and stop processing, giving the line number and filename where the error occurred, along with a given error message. Double-bracket expansions are performed in the message.

{% raise_error "This failed to process!" %}

IRIS-HEP specific tags / blocks

These are designed for IRIS-HEP, and simplify common needs. They are much faster than includes, and more powerful.

expandable (block)

This block will make an expandable list. You give it the number of non-expanded items, and the rest will have a expand button. Inside the block, you have access to the “expandable” item, which is the current looping item.

{% expandable my_array 10 %}
  {{ expandable }}
{% endexpandable%}