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.

Archive page in Crimson

How Crimson builds the Archive page

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

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)

For more details on how to upload the routes.yaml file, please see Upload routes.yaml file

---

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

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.

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

---

Troubleshooting

Archive page shows 404

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.

Archive loads but looks empty

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

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

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