Using Tags in Xanthan

Xanthan includes a built-in tagging system that makes it easy to organize and filter content across your site. The system is designed to be simple, requiring only YAML frontmatter tags on your pages and a single tags page. This page describes how tagging works, and you can see it work on our sample tag page.

How It Works

Adding Tags to Pages

Add tags to any page’s YAML frontmatter:

---
title: Forest
layout: scrollstory
tags:
  - music
  - nature
  - campus
---

Tags are case-insensitive and can contain spaces. Keep them simple and consistent for best results.

The Tags Page

The tags page (/tags/) is configured in its frontmatter:

---
layout: base
title: Tags
summary: Browse by tags
permalink: /tags/
tag-folders: scrollstories
---

The tag-folders parameter tells the page which folder(s) to collect tags from. You can specify a single folder or multiple comma-separated folders.

The page automatically:

  1. Collects all tags from pages in the specified folder(s)
  2. Displays them as clickable badges at the top of the page
  3. Shows cards for all pages, with tags visible on each card
  4. Filters by URL parameter like ?tag=music to show only matching pages
  5. Updates the display dynamically without page reload

URL-Based Filtering

Share direct links to filtered views:

Users can click tag badges on the tags page, or you can link directly to filtered views from anywhere on your site.

Customization

Change the Source Folder

By default, the tags page looks for pages in /scrollstories/. To change this, edit the tag-folders parameter in the frontmatter of tags.md:

Single folder:

---
layout: base
title: Tags
permalink: /tags/
tag-folders: scrollstories
---

Change scrollstories to your preferred folder, like essays or projects.

Multiple folders:

---
layout: base
title: Tags
permalink: /tags/
tag-folders: scrollstories, essays, projects
---

Use a comma-separated list to collect tags from multiple folders. The page will show all tagged content from any of the specified folders.

Multiple Tag Pages

You can create multiple tag pages for different content collections:

Example: /project-tags.md

---
layout: base
title: Project Tags
permalink: /project-tags/
tag-folders: projects
---

Example: /all-tags.md (multiple content types)

---
layout: base
title: All Tags
permalink: /all-tags/
tag-folders: scrollstories, essays, projects
---

Styling Tags

Tag styles are defined in assets/css/cards.css:

Customize colors, sizes, and hover effects by editing these classes.

Tag Display Components

On Cards (Automatic)

The card grid automatically displays tags when present:


{% include nav/card-grid.html cards=site.pages show-tags=true %}

To hide tags on specific card grids:


{% include nav/card-grid.html cards=site.pages show-tags=false %}

Individual Tag Pills

Display tag pills anywhere on your site:

Static tag (display only):

<span class="tag-pill">music</span>

music

Clickable tag (links to filtered view):

<a href="/tags/?tag=music" class="tag-pill">music</a>

music

Use clickable tags to help readers discover related content. Replace music with any tag from your site.

Best Practices

Tag Naming

Good tags: music, history, nature, campus, architecture
Avoid: This is about music history, MUSIC, Music123

Tag Quantity

Shared vs. Unique Tags

Integration with Navigation

Add tag filters to your main navigation by editing _data/top-nav.yml:

- title: "Browse"
  items:
    - title: "All Stories"
      url: "/tags/"
    - title: "Music"
      url: "/tags/?tag=music"
    - title: "History"
      url: "/tags/?tag=history"
    - title: "Nature"
      url: "/tags/?tag=nature"

Troubleshooting

Tags aren’t showing up

Filtering doesn’t work

Cards look wrong