Tags

The Tags page is a dedicated archive page in Crimson that lists every tag which has been used on at least 1 published post.

It’s a great way to help readers discover your content by topic, and it also complements Ghost’s built-in tag collections (for example: /tag/news/, /tag/business/, etc.).

Tags page in Crimson

What the Tags page does in Crimson

The Tags page:

• Displays a list of external tags that have been used on your site.

• Sorts tags by number of posts.

• Links each tag to its tag collection page.

• Supports “Load more tags” using JavaScript + the Ghost Content API, because Ghost 6.x limits API page sizes (more on that below).

Internal Tags (tags that starts with '#') and Tags which are not used will not appear on this page.

---

How Crimson enables the Tags page

Crimson creates the Tags page using a custom route in routes.yaml:

routes:
  /tags/:
    template: tags

This tells Ghost: “When someone opens /tags/, render tags.hbs from the theme.” This is exactly how Ghost template routes work.

---

Prerequisites

1) Upload Crimson’s routes.yaml (required)

If you haven’t uploaded Crimson’s routes.yaml, the /tags/ page won’t work.

Ghost Admin → Settings → Labs → Upload routes YAML.

Step by step instructions to upload routes.yaml are provided in Upload routes.yaml file.

---

2) Content API key (required for “Load more authors”)

Ghost 6 removed limit=all and added a max page size of 100 items per API request, so pages that list “everything” (like Tags/Authors) need pagination.

To support loading more tags, you must set the Content API variables in Code Injection (as explained in Code Injection).

---

Why Crimson uses “Load more tags”

In Ghost 6.x, limit=all no longer returns everything. It now returns up to 100 items max, and you’re expected to paginate if you need more.

That’s why Crimson implements:

• An initial load of tags

• A Load more button to fetch additional tags using pagination

---

How Crimson decides “how many tags to load” initially

Crimson uses the theme’s posts_per_page configuration (from package.json) to decide how many items to load in a batch.

In Ghost themes:

• posts_per_page is defined in package.json

• Available in templates as {{@config.posts_per_page}}

Changing the number of tags loaded per click (advanced)

If you want the Tags page to load more (or fewer) tags per “Load more” action, update your theme’s package.json:

{
  "config": {
    "posts_per_page": 12
  }
}

Then zip the theme and re-upload it (changes to package.json require a restart/re-upload workflow).

This will also change the number of posts and authors being loaded in a single request. Keep this number reasonable (example: 8–15). A very high number can slow down initial page load. For Crimson, I suggest to keep it 12.

---

Notes about internal tags

Ghost supports internal tags (tags starting with #) which are typically used for internal organization or theme-driven features, and are not generally rendered publicly like normal tags.

If you’re using internal tags for Crimson features (e.g., special layouts/flags), don’t expect them to behave like public topic tags.

---

Troubleshooting

The /tags/ page is blank

Common reasons:

• You haven’t added tags to any published posts yet (tags appear when used).

• routes.yaml wasn’t uploaded / is different than Crimson’s recommended routes.

“Load more tags” doesn’t work

Check these in order:

1. Confirm your Content API key + API URL Code Injection variables are present (Crimson requires them for Authors/Tags pagination).

2. Ensure JavaScript is enabled (basic, but the page explicitly relies on it).

3. If your site has 100+ tags, confirm you’re not assuming limit=all will fetch everything (Ghost 6.x requires pagination).