> For the complete documentation index, see [llms.txt](https://docs.themeupstudio.com/crimson/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.themeupstudio.com/crimson/custom-pages/tags.md).

# 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.).

<figure><img src="/files/RKCFO3H4h7ELKUDG23G4" alt=""><figcaption><p>Tags page in Crimson</p></figcaption></figure>

### 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).

{% hint style="warning" %}
Internal Tags (*tags that starts with '#'*) and Tags which are not used will not appear on this page.
{% endhint %}

***

### How Crimson enables the Tags page

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

```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](/crimson/getting-started/upload-routes.yaml-file.md).

***

#### **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](/crimson/getting-started/code-injection.md)).

***

### 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`:

```json
{
  "config": {
    "posts_per_page": 12
  }
}
```

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

{% hint style="warning" %}
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**.
{% endhint %}

***

### 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.&#x20;

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

<details>

<summary>The /tags/ page is blank</summary>

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.

</details>

<details>

<summary>“Load more tags” doesn’t work</summary>

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).

</details>