How to add search to a Ghost site

I wanted to add search functionality to a site I built in Ghost.

You can see the final result of this tutorial on this page: https://ritywool.it/ricerca/.

When you first start dealing with this task you’ll think “it must be simple”.

But for some reason the Ghost software does not provide an easy solution for this, and you need to use a 3rd party plugin and mess with the template. It really needs a developer that knows how to deal with that.

No idea why it’s not a built-in simple solution that does not require a developer like me to spend time to tweak the theme.

It’s weird because they have search in the admin panel, but have no solution for the public facing part of the site. They officially suggest to use Google custom search instead, which is not really a solution in any case.

That’d be understandable for a static site generator, which has no engine to run the search, but Ghost is not a static site generator.

I explored the possible options for a while. One suggested option in their docs is GhostHunter but that didn’t work for me. I tried but got all sorts of JavaScript errors in the console and didn’t have the patience to see what was wrong. Also seems to be abandoned, last commit 2 years ago.

Then I found Ghost Finder and it worked like a charm, so that’s what I’ll explain here.

It’s a JavaScript library that uses the Ghost API to search posts.

First I made a local copy of the site (with npm install ghost-cli -g and ghost install local), with the theme used on the live site. I downloaded the theme from /ghost/#/settings/design.

I downloaded the library and put it under assets.

I created a search page in the Ghost admin with the “/search” URL slug.

Then I went to the editor and made a page-search.hbs file (it’s important the file name after - matches the page slug)

I restarted Ghost with ghost restart in the CLI to make it recognize the page (I only needed this locally, not on the live server).

I use the Casper default theme, this part will differ depending on your theme, but I added to default.hbs the Ghost Finder JavaScript file (which loads on all pages, unfortunately):

<script src='{{asset 'ghost-finder/dist/ghost-finder.js'}}'></script>

right before the </head> tag.

Then in page-search.hbs I copied the content of page.hbs and instead of the page content I added

<div style="text-align: left;">
  <input id='search-input' type='text' placeholder='Search' style="color: black; padding: 20px" />
  <div id='search-result'></div>
</div>

<script>
  new GhostFinder({
    input: '#search-input',
    showResult: '#search-result',
    contentApiKey: 'YOURKEY',
  })
</script>

contentApiKey is a unique key you need to add from your site, otherwise it will not work. Go in the Integrations panel in Ghost Admin and click “Add custom integration”. That will give you the key, then paste it here.

Since the site is not in English I also added a custom search template to translate it in Italian:

new GhostFinder({
  //...,
  resultTemplate: `<ul class="search-results-wrapper">
      <p>Risultati della ricerca: ##resultCount</p>
      ##results
    </ul>`
})

And finally I added a navigation menu to point to the Search page.

That was it. It wasn’t long or complicated for a developer like me, although almost impossible to figure out for everyone else?

It’s one of those things that could easily be automated for us but it’s not and you really feel you’re wasting time working on it.

I hope this article can make it easier for others.