Beyond Pagination: Building an Automated All-Posts Table of Contents in Ghost
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:
- Theme Independent: Zero theme modifications. You can switch from Alto to Casper tomorrow, and your archive page continues to work flawlessly.
- Fully Automated: As soon as a post is published, it appears on the archive page in real time.
- 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.
- 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-keyinside thesodo-searchscript tag. That is your active public Content API key!
Step 2: The Archive Logic
We need our client-side script to:
- Query
/ghost/api/content/posts/requesting only the bare essential fields (title,slug,published_at, andtags) to keep the payload tiny (typically <10 KB for dozens of posts). - Sort and group the posts by publication year.
- Render a clean list featuring direct links, publication dates, and category badges.
- Attach an
inputlistener 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:
- In Ghost Admin, navigate to Settings ? Navigation.
- Add a new primary link with the label Archive pointing to
/archive/. - 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.