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!