Working around a blog navigation bug in Ghost's Braun theme

Setting up the blog, I noticed that while excluded from the home page, posts intended for the Updates section of my site (tagged now) are showing up on the blog.

This is wrong! Those posts should only be on the dedicated /now/ page. They're showing up there just fine. So why are they here, too?

Diagnosis

Ghost CMS stores all pages and posts in a single database, but uses a file called routes.yaml to determine which posts/pages show up, where, and how they'll be formatted. So let's check out how the blog is routed.

  /blog/:
    permalink: /{slug}/
    template: blog
    data: page.blog
    filter: tag:-[books,now,hash-timeline,hash-gallery]

Line 5 is what we're interested in. It says: Filter out all posts with the following tags: books, now, #timeline, #gallery.

Weird: so the blog should be working properly and leaving out now posts. Time for some troubleshooting.

I made posts with each of the four filters the blog page should exclude. Is the filter broken for all of them, or just now?

Answer: the filter is working for internal tags (hash-timeline and hash-gallery) but not for public tags (now and books).

Why?

I have no clue.

OK, I could guess. It's true that now and books shouldn't be showing up anywhere on the blog—but the filter seems to be partly working; they're only showing up under their category headings, but not under the default All section. This suggests to me that somewhere in the theme—probably the blog.hbs file—the routing filters are being applied to part of the blog template (All) but aren't being applied to the part of the template that defines blog category navigation.

This would explain why now and books posts aren't shown in All but do show up under their procedurally generated section headers.

And it could also explain why #gallery and #timeline posts aren't showing up: they're internal tags. Since they're backend tools intended to always be invisible to site visitors, there may be some separate logic written into the theme that's making sure those tags don't show up here.

But I'm not going to poke around in the files to find out. I'm not going to fix the root of the problem. By this point I've spent fifteen minutes on this—not a ton of time, but I don't want to get sucked into an hour or two of fiddling. My priority today is site content, not structure, function, or design.

We know enough now to figure out a quick fix.

And besides—I don't know how to code.

Solutions

Retagging

One option would be abandon the problem tags, relabel posts with a new internal tag (eg. change out now for #now) and then modify the routes.yaml to filter those instead. I tried and it works.

Defined Sections

Another option involves no code and no re-tagging.

The admin panel, under Design & Branding, allows you to manually set the Blog category navigation.

We could just list out what sections we want for the blog right here, and bingo: no more problem sections.This is super easy—if this were an established site, it would be the obvious choice.

But I don't love this solution. I'm in early stages of building this site, and I'll be adding content all week. As I create new posts and notice new groupings/patterns, I'll be constantly adjusting tags. I'd rather have new sections appear here by default so I can see how it looks, rather than having to manually add new sections in the admin panel every time I add a new tag. The list of sections I don't want is shorter and more definite than the list of sections I do.

Defined Exclusions

As I stared down that Blog category navigation text box, something occurred to me. In the routes file, recall that the programming language (in this case, Handlebars) used a hyphen to mean exclude.

filter: tag:-[books,now,hash-timeline,hash-gallery]

The admin panel says that this setting is for us to "add slugs for category navigation of the blog page." But it begs the question: what happens if we try to add a negative? Can we filter out certain tags, and might that get around whatever filter error is impacting our routes.yaml file?

I tried it out...

And it almost worked.

At first I thought it did work. The problem sections were gone! Since I didn't have any posts tagged under "real" headings, I figured I was in the clear.

But after some experimentation, I found that now no sections would appear in the blog navigation no matter what they were.

So in the end, my first solution - Retagging with internal tags - was my best bet.

Good enough for me.

–hcjs