Beyond Pagination: Building an Automated All-Posts Table of Contents in Ghost

Beyond Pagination: Building an Automated All-Posts Table of Contents in Ghost
Photo by Glenn Carstens-Peters / Unsplash

Ghost is built for distraction-free publishing, but once your blog grows past dozens of articles, standard pagination becomes a major barrier to discovery. Here is the rationale and implementation for building a dynamic, client-side Archive and Table of Contents page without touching theme files or breaking updates.


The Problem: The "Pagination Tax" on Growing Blogs

Ghost is arguably one of the cleanest, most elegant publishing platforms available today. Its editor is top-tier, and its themes emphasize readability and typography over clutter.

However, Ghost's out-of-the-box navigation model has a glaring limitation: it relies almost entirely on chronological reverse-feed pagination.

When you start a blog with three or four posts, a five-posts-per-page feed feels clean and minimal. But fast-forward a couple of years. Once your library scales to 30, 50, or 100+ articles:

  • Discovery grind: Finding an older homelab blueprint, hardware review, or deep dive requires clicking "Older Posts" through six, seven, or ten consecutive pages.
  • The Search Fallacy: While Ghost's native search modal (sodo-search) is fast, search assumes the reader already knows what keyword to look for. It doesn't help visitors who simply want to browse the breadth of your writing or explore topics chronologically.
  • No Default Archive: Unlike WordPress, which historically provided widgetized annual archives out of the box, standard Ghost themes rarely include a dedicated single-page table of contents for your entire post catalog.

I needed a single, centralized Table of Contents / Archive page: grouped chronologically by year, tagged, instantly searchable, and 100% automated so I never have to update it manually.


The Architectural Options (And Why Client-Side Wins)

When solving this in Ghost, there are three common architectural paths:

Approach A: Manual Static Markdown List

You create a static page titled "Archive" and manually type out every post link. While trivial to set up, it requires ongoing manual labor. Forget to update the page after publishing a post, and your archive is immediately out of date. Verdict: Unacceptable maintenance overhead.

Approach B: Custom Handlebars Theme Templates (page-archive.hbs)

Ghost allows developers to create custom templates using Handlebars and the {{#get "posts" limit="all"}} helper. The server compiles the entire post catalog directly into the HTML response.

While performant, it comes with friction for self-hosters and managed Ghost users alike:

  • You have to download, unzip, edit, re-zip, and re-upload your theme.
  • If you use an official theme (like Alto, Casper, or Edition), any upstream theme update will overwrite your custom template.
  • You can't easily iterate on styling or features without a theme redeployment cycle.

Approach C: The Content API + HTML Card (The Winner)

Ghost exposes a blazing-fast, read-only Content API designed specifically for public consumption. Ghost's own search bar already queries this API on every page load.

By dropping a lightweight vanilla JavaScript snippet into an HTML Card on a standard Ghost Page, we get the best of all worlds:

  1. Theme Independent: Zero theme modifications. You can switch from Alto to Casper tomorrow, and your archive page continues to work flawlessly.
  2. Fully Automated: As soon as a post is published, it appears on the archive page in real time.
  3. Client-Side Instant Filtering: We can provide an interactive search bar that filters titles and tags in milliseconds directly in memory, without round-trips to the server.
  4. Zero Dependencies: Pure vanilla JS and CSS. No jQuery, no React, no external CDNs to fail.

The Implementation: How to Build It

Step 1: Grab Your Content API Key

Ghost requires a Content API key to fetch published posts. You have two easy ways to get this:

  • Via Ghost Admin: Go to Settings ? Integrations ? Add custom integration. Name it "Archive Page" and copy the generated Content API Key (a 26-character hex string).
  • Via Page Source: If your theme already has Ghost Search enabled, open your blog homepage, view source, and search for data-key inside the sodo-search script tag. That is your active public Content API key!

Step 2: The Archive Logic

We need our client-side script to:

  1. Query /ghost/api/content/posts/ requesting only the bare essential fields (title, slug, published_at, and tags) to keep the payload tiny (typically <10 KB for dozens of posts).
  2. Sort and group the posts by publication year.
  3. Render a clean list featuring direct links, publication dates, and category badges.
  4. Attach an input listener to a search box to provide instant, real-time filtering across both post titles and tags.

Step 3: The Complete Code Snippet

Create a new Page in Ghost titled "Archive" (slug: archive). Add an HTML card, and paste the following snippet (replacing YOUR_CONTENT_API_KEY with your key):

<div class="archive-wrapper" style="max-width: 800px; margin: 0 auto; padding: 10px 0;">
  <p style="opacity: 0.7; font-size: 1.05rem; margin-bottom: 24px;">
    A complete chronological index and table of contents of all published articles and notes.
  </p>
  
  <div style="margin-bottom: 28px;">
    <input type="text" id="archive-filter" placeholder="Filter articles by title or tag..." 
      style="width: 100%; box-sizing: border-box; padding: 12px 16px; font-size: 1rem; border-radius: 8px; border: 1px solid rgba(125, 125, 125, 0.25); background: rgba(125, 125, 125, 0.05); color: inherit; outline: none; transition: border-color 0.2s;" />
  </div>

  <div id="archive-container">
    <p id="archive-loading" style="opacity: 0.6; font-style: italic;">Loading article index...</p>
  </div>
</div>

<style>
  .archive-year-group { margin-top: 36px; margin-bottom: 16px; }
  .archive-year-heading {
    font-size: 1.6rem; font-weight: 700; margin: 0 0 16px 0; padding-bottom: 8px;
    border-bottom: 2px solid rgba(125, 125, 125, 0.2);
  }
  .archive-list { list-style: none !important; padding: 0 !important; margin: 0 !important; }
  .archive-item {
    display: flex; justify-content: space-between; align-items: baseline;
    padding: 10px 0; border-bottom: 1px solid rgba(125, 125, 125, 0.1);
    gap: 16px; flex-wrap: wrap;
  }
  .archive-item:last-child { border-bottom: none; }
  .archive-link {
    font-weight: 500; text-decoration: none; color: inherit;
    font-size: 1.05rem; flex: 1 1 60%; transition: opacity 0.15s ease;
  }
  .archive-link:hover { opacity: 0.7; text-decoration: underline; }
  .archive-meta {
    font-size: 0.85rem; opacity: 0.65; white-space: nowrap;
    display: inline-flex; align-items: center; gap: 8px;
  }
  .archive-tag {
    font-size: 0.75rem; padding: 2px 8px; border-radius: 12px;
    background: rgba(125, 125, 125, 0.15); color: inherit; font-weight: 500;
  }
  @media (max-width: 600px) {
    .archive-item { flex-direction: column; gap: 4px; }
    .archive-meta { font-size: 0.8rem; }
  }
</style>

<script>
  (async function() {
    const container = document.getElementById('archive-container');
    const loading = document.getElementById('archive-loading');
    const filterInput = document.getElementById('archive-filter');
    let allPosts = [];

    function renderPosts(postsToRender) {
      if (postsToRender.length === 0) {
        container.innerHTML = '<p style="opacity: 0.6; padding: 20px 0;">No articles found matching your filter.</p>';
        return;
      }
      let currentYear = null;
      let html = '';

      postsToRender.forEach(post => {
        const date = new Date(post.published_at);
        const year = date.getFullYear();
        const dateStr = date.toLocaleDateString('en-US', { month: 'short', day: 'numeric' });

        if (year !== currentYear) {
          if (currentYear !== null) html += '</ul></div>';
          currentYear = year;
          html += <div class="archive-year-group"><h2 class="archive-year-heading"></h2><ul class="archive-list">;
        }

        const tagBadge = (post.tags && post.tags.length > 0)
          ? <span class="archive-tag"></span> : '';

        html += 
          <li class="archive-item">
            <a class="archive-link" href="//"></a>
            <div class="archive-meta">
              <span></span>
              
            </div>
          </li>;
      });

      if (currentYear !== null) html += '</ul></div>';
      container.innerHTML = html;
    }

    try {
      const res = await fetch('/ghost/api/content/posts/?key=YOUR_CONTENT_API_KEY&limit=all&fields=title,slug,published_at&include=tags');
      const data = await res.json();
      allPosts = data.posts || [];
      if (loading) loading.remove();
      renderPosts(allPosts);

      filterInput.addEventListener('input', function(e) {
        const query = e.target.value.toLowerCase().trim();
        if (!query) {
          renderPosts(allPosts);
          return;
        }
        const filtered = allPosts.filter(p => {
          const inTitle = p.title.toLowerCase().includes(query);
          const inTag = p.tags && p.tags.some(t => t.name.toLowerCase().includes(query));
          return inTitle || inTag;
        });
        renderPosts(filtered);
      });
    } catch (err) {
      if (loading) loading.innerText = 'Failed to load article archive.';
    }
  })();
</script>

Step 4: Linking to Primary Navigation

Once you publish the page, make it front-and-center for your readers:

  1. In Ghost Admin, navigate to Settings ? Navigation.
  2. Add a new primary link with the label Archive pointing to /archive/.
  3. Save your changes.

Your visitors now have a one-click gateway to scan every article you've ever written, complete with instant live search and year-based categorization.


Summary

Homelab and tech blogging is all about building sustainable, low-maintenance systems. By taking advantage of Ghost's decoupled Content API, we solved a fundamental content discovery bottleneck without hacking theme code or introducing ongoing chores.

You can see the final implementation live in action right now on our Archive Page.

Fahim

Fahim

Engineer, husband, dad, and photography enthusiast documenting technology, creativity, and the occasional rabbit hole.
Ottawa, ON