Setting up filters
To configure filters in Pagefind, pages are associated to filter keys and values using data attributes.
#Capturing a filter value from an element
<h1>My Blog Post</h1>
<p>
Author:
<span data-pagefind-filter="author">CloudCannon</span>
</p>
An element tagged with data-pagefind-filter will associate that page with the filter name, and capture the contents of the element as the filter value. In the above example, the page would be tagged as author: ["CloudCannon"].
Filters can have multiple values per page, so the following is also valid:
<h1>Hello World</h1>
<p>
Authors:
<span data-pagefind-filter="author">CloudCannon</span>
and
<span data-pagefind-filter="author">Liam Bigelow</span>
</p>
Which produces: author: ["CloudCannon", "Liam Bigelow"].
#Capturing a filter value from an attribute
If the data you want to filter on exists as an attribute, you can use the syntax filter_name[html_attribute]
<head>
<meta
data-pagefind-filter="author[content]"
content="Pagefind"
property="og:site_name">
</head>
This will capture the filter value from the attribute specified, in this case producing author: ["Pagefind"].
#Specifying a filter inline
If your value doesn’t already exist on the page, you can use the syntax filter_name:value:
<h1 data-pagefind-filter="author:CloudCannon">Hello World</h1>
This will tag this page as author: ["CloudCannon"]. The element this is set on does not matter, meaning this attribute can be located anywhere that is convenient in your site templating.
#Specifying multiple filters on a single element
Filter captures may be comma separated and all will apply. The exception is specifying a filter inline, which may only be the last item in a list.
For example:
<h1
data-section="Documentation"
data-category="Article"
data-pagefind-filter="heading, tag[data-section], tag[data-category], author:Freeform text, captured to the end">
Hello World
</h1>
This will produce the filter values for the page:
{
"heading": ["Hello World"],
"tag": ["Documentation", "Article"],
"author": ["Freeform text, captured to the end"]
}
#Notes
The
data-pagefind-filterattribute does not need to be within the<body>, or thedata-pagefind-bodytag.
The
data-pagefind-filterattribute will still apply if set on or within adata-pagefind-ignoreelement.
The keys
any,all,none, andnotare reserved and can’t be used as filter keys.