Hacking Ghost: Adding Mobile-Friendly Breadcrumbs to the Edition Theme

The "Lost User" Problem

We spend hours tweaking our homelabs, optimizing Docker containers, and fine-tuning our firewalls. But often, we neglect the actual interface of our documentation.

If you are running a technical blog on Ghost (specifically the "Edition" theme), you might have noticed a missing feature: Navigation Breadcrumbs. I've been running and customizing Ghost Edition them for just about a year, but 'live' since July 2025. I've quickly discovered some things!

When a user lands on a deep-dive tutorial like my "Ultimate Arr Stack Guide," they often want to click back to the "Self-Hosting" category to see what else you have written. Without breadcrumbs, they have to hit the browser "Back" button—or worse, they just leave.

Today, we are going to fix that. We are going to inject a Sidescrolling, Mobile-Responsive Breadcrumb Bar directly into the Ghost theme code.

Why Do This? (The SEO & UX Win)

Before we hack⚫ the code, here is why this matters for your own "Digital Fortress":

1. Siloing for Google: Breadcrumbs tell Google exactly how your site is structured (Home > Category > Post). This helps you rank for broad terms like "Self-Hosting" rather than just specific tutorial titles.
2. Mobile UX: On a phone, screen real estate is expensive. Standard breadcrumbs often wrap to two lines and look ugly. We are going to build a "Swipeable" path that stays on one clean line, no matter how deep your hierarchy goes.

Step 1: The Template Edit

We need to edit the theme's HTML structure to insert the link list. We will place it at the very top of the post header so it’s the first thing a user sees.

Warning: This requires editing your theme files.

1. Go to Ghost Admin → Settings → Design → Change Theme → Advanced → Download.
2. Unzip the folder and open partials/content.hbs in your code editor (VS Code, Notepad++, etc.).

You can also simply SSH to your server and edit the file directly, if you'd prefer.

Find the <header> block. In the Edition theme, it looks like this:

<header class="single-header gh-canvas">

We want to paste our logic immediately after that line, but before the metadata (dates/tags).

Copy and Paste this Code Block:

{{!-- Core Lab Breadcrumbs Logic --}}
            {{#is "post"}}
                <div class="breadcrumbs-container">
                    <ol class="breadcrumbs">
                        <li><a href="{{@site.url}}">Home</a></li>
                        {{#primary_tag}}
                            <li><a href="{{url}}">{{name}}</a></li>
                        {{/primary_tag}}
                        {{#foreach tags from="2" limit="2"}}
                            <li><a href="{{url}}">{{name}}</a></li>
                        {{/foreach}}
                        <li class="current">{{title}}</li>
                    </ol>
                </div>
            {{/is}}

Save the file, restart ghost - docker compose restart ghost

Step 2: The "Sidescroll" CSS

Now that the HTML is there, we need to style it. If we don't, it will look like a messy bulleted list.

We will use CSS to force the list onto a single line and enable horizontal scrolling for mobile devices.

Go to Ghost Admin → Settings → Code Injection → Site Header. Paste this into the <style> block:

/* --- Core Lab Breadcrumbs Style --- */
.breadcrumbs-container {
    width: 100%;
    max-width: 100vw; /* Safety: prevents page-wide scroll issues */
    overflow-x: auto; /* Enables the horizontal swipe */
    white-space: nowrap; /* Forces single line */
    padding-bottom: 10px;
    margin-bottom: 5px;
    -webkit-overflow-scrolling: touch; /* Smooth momentum scroll on iOS */
    scrollbar-width: none; /* Hide scrollbars for Firefox */
}

/* Hide scrollbars for Chrome/Safari but keep functionality */
.breadcrumbs-container::-webkit-scrollbar {
    display: none;
}

.breadcrumbs {
    list-style: none;
    padding: 0;
    margin: 0;
    display: inline-flex;
    font-size: 1.3rem; /* Adjust to match your theme's body font */
    font-weight: 600;
    text-transform: uppercase;
    letter-spacing: 0.5px;
}

.breadcrumbs li {
    display: inline-block;
}

/* The Separator (Slash) */
.breadcrumbs li:not(:last-child)::after {
    content: "/"; 
    margin: 0 10px;
    opacity: 0.5;
    color: var(--ghost-accent-color); /* Uses your brand color automatically */
}

.breadcrumbs li a {
    text-decoration: none;
    color: var(--ghost-accent-color);
}

.breadcrumbs li a:hover {
    text-decoration: underline;
}

/* The "Current Page" (Greyed out) */
.breadcrumbs li.current {
    color: var(--color-secondary-text); 
    opacity: 0.7;
    pointer-events: none; /* Make it unclickable */
}

This is a great time to review your code injection code overall, if you have other additions in there and clean up / optimize it. I am not a developer so I had a little help from my friend😃

Step 3: Deploy & Restart

1. Zip your theme folder back up.
2. Upload it to Ghost Admin.
3. Restart Ghost.
4. Crucial Step: If you use Cloudflare, Purge Your Cache!
   • Since we edited a .hbs file, the HTML structure of your site changed. Cloudflare will serve the old version until you force a refresh.

🏁The Final Result

Load up a post on your phone. You should see a neat path like: HOME / SELF-HOSTING / DOCKER... Similar to this -

If the path is too long to fit? Just swipe right. It flows perfectly without breaking your site's layout.

Now your users—and the Google bots—will never get lost in your lab again!

❓ Frequently Asked Questions (FAQ)

Why don't Ghost themes include breadcrumbs by default?

Most free Ghost themes, including Edition, are built for simplicity and don't assume a deep tag/category hierarchy. Breadcrumbs require reading a post's primary tag and additional tags to build a navigation path, which isn't part of the default template logic — you have to add it yourself by editing the theme's content.hbs partial.

Will this breadcrumbs hack survive a theme update?

No. Since the breadcrumb logic lives inside the theme's content.hbs file, updating to a newer version of the theme overwrites your custom edit along with any other theme customizations you've made. You'll need to re-apply the change (and any other hacks) after every theme update.

Why do breadcrumbs matter for SEO?

Breadcrumbs tell Google exactly how your site is structured — Home > Category > Post — which helps you rank for broader category terms (like "Self-Hosting") rather than only the exact title of a single tutorial. It's a small structural signal that reinforces your site's information hierarchy.

Why make the breadcrumb bar horizontally scrollable instead of wrapping?

On mobile, a wrapped breadcrumb list eats up two lines of precious screen space and looks messy. Forcing it onto a single scrollable line with white-space: nowrap and overflow-x: auto keeps the layout clean regardless of how deep the tag hierarchy goes — users just swipe right to see the rest of the path.

Do I need to touch Code Injection or just the theme file?

Both. The HTML structure (the actual breadcrumb links) goes into the theme's content.hbs partial, while the styling that makes it scrollable and readable goes into Ghost Admin's Site Header code injection. Skipping the CSS step leaves you with an unstyled, messy bulleted list.

Why do I need to purge my Cloudflare cache after this change?

Because editing a .hbs file changes your site's actual HTML structure, not just its content. If you're using Cloudflare, it will keep serving the old cached HTML until you force a cache purge, so the new breadcrumb markup won't appear for visitors until you do.