> 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/archive.md).

# Archive

The **Archive** page in Crimson is a dedicated page that lists **all published posts** and groups them by **month**, so readers can quickly browse your back-catalog without digging through pagination on the homepage. Crimson includes this as a **custom route** in `routes.yaml`.

<figure><img src="/files/hEFMF9eMl9O7PVXr4xFF" alt=""><figcaption><p>Archive page in Crimson</p></figcaption></figure>

### How Crimson builds the Archive page

Crimson’s Archive page is powered by a **custom route** that uses Ghost’s **channel controller**:

```yaml
routes:
  /archive/:
    template: archive
    controller: channel
```

#### What each line means

* **`/archive/`** This is the URL visitors will open (your-site.com/archive/).
* **`template: archive`** Ghost will render this route using the theme template **`archive.hbs`**.
* **`controller: channel`** A **channel** is a “paginated stream of content” (think: permanent search results). Importantly, channels **do not change your post URLs**, so your posts can keep their normal `/my-post-slug/` URLs while still appearing inside the archive listing.

***

### Prerequisites

#### 1)  `routes.yaml` is uploaded (required)

The Archive page is created via `routes.yaml`. If your theme routes were not uploaded, `/archive/` will return a **404**.

1. Go to **Ghost Admin → Settings → Labs**
2. Find the **Routes** section
3. Upload Crimson’s `routes.yaml` (or your edited version that includes the Archive route)

{% hint style="info" %}
For more details on how to upload the `routes.yaml` file, please see [Upload routes.yaml file](/crimson/getting-started/upload-routes.yaml-file.md)
{% endhint %}

***

### Pagination behavior on the Archive page

Ghost automatically paginates channel routes.

#### “Load more” vs “Paginated pages”

Crimson supports two pagination experiences:

* **Load more**: Readers click a button (example text: “Load 12 more posts”)
* **Paginated pages**: Readers use page navigation and the URL changes like `/archive/page/2/`.

To change this behaviour, see [Code Injection](/crimson/getting-started/code-injection.md) to add/modify values.

***

### Customization options

#### Change how many posts appear per “page”

Ghost controls “posts per page” via theme config in `package.json` (`config.posts_per_page`). Ghost exposes it as `{{@config.posts_per_page}}`.

**What this changes in practice:**

* If `posts_per_page` is 12, your archive will show **12 posts** before moving to `/archive/page/2/` (or before “Load more” loads the next batch).

{% 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 %}

{% hint style="warning" %}
Note: Updating `package.json` is a theme-code change. After editing, you typically re-zip and re-upload the theme (and in some environments Ghost may require a restart for config changes).
{% endhint %}

***

### Troubleshooting

<details>

<summary>Archive page shows 404</summary>

Most common causes:

* **routes.yaml wasn’t uploaded** after activating Crimson: Crimson requires uploading `routes.yaml` for custom pages like `/archive/`.
* **The Archive route is missing or indented incorrectly:** YAML is indentation-sensitive.

</details>

<details>

<summary>Archive loads but looks empty</summary>

You may not have enough **published posts** yet. Publish a few posts and refresh.

</details>

<details>

<summary>Pagination URLs don’t work (e.g., <code>/archive/page/2/</code>)</summary>

* Confirm your Archive route uses `controller: channel` (channels are paginated streams by design).
* If you’re using “Load more” mode, check your Code Injection pagination variable settings (as per your Crimson setup).

</details>