Tags

A page lives somewhere — in your nav, inside a section, at an address that says where it sits. An article lives nowhere in particular: it arrives, and the only thing that orders it is its date.

A tag is the other way of grouping things. It is a word you put on a post, and a list can filter by it.

What a tag is, and what it is not

A word. recipes, news, case-study.

There is no tag record anywhere in the product. A tag has no description, no picture of its own, no label separate from the word, and no order you arrange them in. There is no screen listing them and nothing to tidy up.

The tags your site has are the tags on its posts. Take the last one off the last article and it has stopped existing. That is the whole design, and what it buys is that there is nothing to keep in step.

The shape

Lowercase letters, digits, and hyphens where you would put a space: case-study, never Case Study. At most 20 tags on a post, at most 40 characters each.

The box slugifies as you type, so typing Sourdough Tips gives you sourdough-tips before you have saved anything.

It matters because a template matches a tag exactly. A list filtered on Recipes against an article tagged recipes is not an error and not a warning — it is an empty list on a page that looks perfectly fine.

Putting one on

Open any page, article, block or form, go to its Settings tab, and the Tags box is in the right-hand column under Picture. Type and press Enter, or a comma. Backspace on an empty box takes the last one back, and the × on a chip removes it.

It suggests the tags you already have. Start typing and your site’s own tags appear under the box; ↑ and ↓ move through them and Enter or Tab takes one.

That is worth using rather than typing past. recipe on one article and recipes on the next are two different tags, not one — and the page listing one of them will be quietly half-empty, which is exactly the kind of wrong that nobody notices.

Blocks and forms have them too

Nothing on your site reads a block’s tags or a form’s. They are there for the admin’s own lists: once you have forty blocks, a tag is how you tell “Header (old)” from “Header”.

Listing one tag

{% assign recipes = collections.articles | where: "tags", "recipes" %}
{% for post in recipes %}
  <h3><a href="{{ post.url }}">{{ post.title }}</a></h3>
{% else %}
  <p>Nothing here yet.</p>
{% endfor %}

Pages work the same way — site.pages | where: "tags", "guide" — and the same rule applies as everywhere else: build the list with assign first, then loop it. See Sorting and filtering.

Showing a post’s own tags

{% if page.tags.size > 0 %}
  <ul class="tags">
    {% for tag in page.tags %}
      <li>{{ tag | replace: "-", " " | capitalize }}</li>
    {% endfor %}
  </ul>
{% endif %}

{{ tag | replace: "-", " " | capitalize }} is how you turn slow-bread into Slow bread for a reader. There is no separate display name to fill in — the word is the whole tag, and the display is the template’s job.

Every tag also becomes a class on the page’s <body>, as mb-tag-recipes, so your site stylesheet can style everything tagged one way without any page needing to know.

A tag page is an ordinary page

Nothing generates /blog/tag/recipes for you. If you want a page for a tag, you make one: a page called Recipes, with the loop above on it. It is in your nav, in your sitemap, and it has its own title, description and whatever else you want to say at the top of it — because it is a page like every other page.

That is a decision rather than something missing. A generated address is one the product has to name, cache, invalidate and keep working when you rename the tag it was built from — and what you would get for all of that is a page you cannot write a word of.

A list of every tag

site.tags is every tag on any page or article, sorted, with nothing repeated:

{% for tag in site.tags %}
  <a href="/blog?tag={{ tag }}">{{ tag | replace: "-", " " | capitalize }}</a>
{% endfor %}

Where those links should point depends on what you built. If you made a page per tag, link to those pages by their real addresses. If you would rather have one index that narrows itself, ?tag= on the end of its own address is the shape to use — a tag is slug-shaped precisely so it can sit in a link with nothing escaped — and a few lines of site JavaScript can hide the cards that do not match.

What goes wrong

A tag nobody uses. A list filtered on a tag that is on no page or article publishes with a warning naming the tags you do have. It is a warning rather than a refusal because a topic you have not written yet is a perfectly good empty list — but it is also what a retag leaves behind, and that one is worth reading.

where with nothing to match. where needs a field and a value. Publishing refuses one with only a field and tells you so. See When something is wrong.

A tag is not a field on the post. page.tags is a list of words, so page.tags.size, page.tags.first and page.tags.last work — anything else off it, like page.tags.name, will not publish. To read the words themselves, loop over the list or use | join.