Mappings

Mappings write the values of a row into the base page. Add them on the group’s Mappings page with Add mapping. Each mapping has a Type, a Target, a Record field and, depending on the type, a Mode or an Attribute.

Mappings work on the complete rendered HTML of the page, theme output included, and run in the order they are listed. They use simple pattern matching rather than a full HTML parser, and each mapping changes only the first element it matches. A mapping whose field the row does not have leaves the page unchanged.

The Record field names a field of the row. A dot reaches into nested data, so address.city reads city inside the row’s address object.

HTML tag

Writes the value into the first element with a given tag name.

• Target: the tag name, such as h1, h2 or title
• Mode: Replace, Append or Prepend the element’s contents

A tag mapping on h1 with the field heading turns the first <h1> into the row’s heading. Use a tag mapping on title to change the HTML <title> element; its value is written as plain text, while other tags accept HTML. Give the element placeholder contents: the pattern does not match an empty one.

When Replace finds an element whose contents are a single child element, such as <h1><span>Text</span></h1>, it keeps the child and replaces the child’s contents.

CSS selector

Writes the value into the first element a selector names, or into one of its attributes.

• Target: the selector
• Mode: Replace, Append or Prepend the element’s contents
• Attribute: optional; when set, the value replaces that attribute instead of the contents

Three selector forms are supported:

• .name matches the first element that has the class name
• #name matches the element whose id is name
• a bare tag name, such as h2, matches the first element with that tag

Combined, nested and attribute selectors such as p.lead, .hero .title or [data-title] match nothing.

The element’s contents end at its own closing tag, even when the same tag nests inside it. Replace keeps a single child element as a tag mapping does, so <p id="intro"><strong>Text</strong></p> keeps its <strong>.

The Attribute option rewrites an attribute the element already has, on the first element that matches the selector and carries that attribute; it never adds one. Use it for an image’s src or alt, a link’s href, or a data- attribute.

List

Fills an existing list with the items of an array field. A list mapping creates no elements: it reuses the <li> elements already in the base page.

• Target: the container, as .class, #id or a tag name
• Record field: the field that holds the array

For example, a base page with this markup:

<div id="benefits">
  <ul>
    <li><span>First benefit</span></li>
    <li><span>Second benefit</span></li>
    <li><span>Third benefit</span></li>
    <li><span>Fourth benefit</span></li>
    <li><span>Fifth benefit</span></li>
  </ul>
</div>

with a list mapping whose target is #benefits and whose field is benefits, and a row with "benefits": ["Fast", "Reliable", "Secure"], keeps the first three <li> elements with the three items and removes the other two.

How the items are placed:

• the first <li> in the container gets the first item, the second the second, and so on
• in each <li>, the item replaces the contents of the first <span> that has no attributes; give that <span> placeholder text, because an empty one is not replaced. Other markup in the <li>, such as an icon, stays
• <li> elements beyond the length of the array are removed
• items beyond the number of <li> elements are dropped, so the base page needs as many placeholders as the longest list in your data
• a field that is missing or not an array leaves the list unchanged

The container is found more loosely than a selector mapping’s element: .name matches any element whose class attribute contains name anywhere, and the container ends at the first closing tag with its name. Prefer an id, and do not nest an element of the container’s tag inside it.

The field must hold an array. JSON file, JSON URL and REST API sources can provide one. CSV, Google Sheets and Notion rows hold only flat values (a Notion multi-select arrives as one comma-separated string), so they cannot feed a list mapping.

Page metadata

Sets a meta tag in the page’s head.

• Target: the meta tag, such as description, keywords, og:title, og:image or twitter:title

Targets that start with og: are written as <meta property="…">, all others as <meta name="…">. Rank replaces the first existing tag whose name or property and content are its only attributes, in either order; when there is none, it adds the tag before </head>.

To change the page’s <title>, use an HTML tag mapping on title.

Changing values in code

Every value a tag, selector or meta mapping writes passes through the sleekRank/replacement/value filter and then sleekRank/replacement/value/{type}, and the page’s HTML passes through sleekRank/replacements/before and sleekRank/replacements/after around the mappings. A plugin can also add its own mapping type through sleekRank/register/replacements. See Hooks.