Site search with Tipue for Pelican

One of the things that's been really missing from Futurile is a site search capability. There are a couple of different options out there including Tapir, Swiftype and plain Google custom search.

In the end I decided that I'd use Tipue if only because there was already a Pelican plugin for it. There's a very good blog post by Moparx which I really cribbed off to get it running.

Essentially, as the site is static the way that Tipue works is that it creates a JSON file when you're generating your static site. This file has all the important elements of the content of your site in it, in a structured format. Then the search is done within your browser - the browser loads a Javascript search and the JSON file. When the user runs the search it searches through the file and displays the results.

What you're losing by using this method is that there's no complex search capabilities and you don't have a log of the searches that have been run on your site.

But for a small site like mine it's more than sufficient. Here are the steps I followed to get it up and running on Pelican version 3.3.

1. Get into your Pelican virtualenv

$ workon <Pelicanvirt>

2. Install beautiful soup which is needed by the Tipue search plugin

(Pelicanvirt)$ pip install beautifulsoup4

3. Download Tipue and install it into your theme folder

(Pelicanvirt)$ cd themes/<nameoftheme>/static/
(Pelicanvirt)$ wget http://www.tipue.com/search/tipuesearch.zip
(Pelicanvirt)$ unzip tipuesearch.zip
(Pelicanvirt)$ rm -rf __MACOSX
(Pelicanvirt)$ mv "Tipue Search 3.1" tipuesearch

I downloaded Tipue from the main site but the zip has a lot of junk in it that I had to delete so it might be better to get it from Github. The files later on depend on the directory path being 'tipuesearch'.

3. Get the search plugin

To easiest way to use all the Pelican plugins is to clone the whole of the pelican plugins git repository and work from there. With this method you'll have all the plugins available to you, though it does take up more space

# Move to the top dir of the virtualenv
(Pelicanvirt)$ cdproject
(Pelicanvirt)$ git clone https://github.com/getpelican/pelican-plugins plugins

You should see a tipue_search plugin directory which has a RST file you can read with further details on the plugin.

4. Edit your pelicanconfy.py

PLUGIN_PATH = 'plugins/'
PLUGINS = ['tipue_search',]

To enable the specific plugin you specify it in your pelicanconf.py. It's a list so you may have more than one plugin specified. Note that PLUGINS_PATH is the relative path from pelicanconf.py to the plugins directory.

5. Check that it creates the JSON file

(Pelicanvirt)$ make html
(Pelicanvirt)$ find ./ -name "tipuesearch_content.json"
(Pelicanvirt)$ less tipuesearch_content.json

The plugin should be up and running and creating the JSON file in the top directory of your output.

6. Create a search page:

Moparx put search on his site's navigation bar, so if you'd like to do it that way his post is worth reading. For Futurile I want search to be a separate page that is linked from my navigation bar. To do this I created a new static page called search.html:

 1     {% extends "base.html" %}
 2 
 3     {% block head %}
 4     <link rel="stylesheet" href="{{ SITEURL }}/theme/tipuesearch/tipuesearch.css">
 5     {{ super() }}
 6     {% endblock head %}
 7 
 8     {% block title %}
 9     Search - {{ SITENAME|striptags }}
10     {% endblock title %}
11 
12     {% block content %}
13     <div id="page">
14     <h1 class="emphtext">Search</h1>
15 
16     <script type="text/javascript"
17             src="http://ajax.googleapis.com/ajax/libs/jquery/2.0.0/jquery.min.js"></script>
18     <script type="text/javascript"
19             src="{{ SITEURL }}/theme/tipuesearch/tipuesearch_set.js"></script>
20     <script type="text/javascript"
21             src="{{ SITEURL }}/theme/tipuesearch/tipuesearch.min.js"></script>
22 
23     <script>
24     $(document).ready(function() {
25      $('#tipue_search_input').tipuesearch({
26              'show': 10,
27             'mode': 'json',
28             'contentLocation': '{{ SITEURL }}/tipuesearch_content.json',
29             });
30     });
31     </script>
32 
33     <section id="content" class="body">
34             <div align="center"><input type="text" size="60" id="tipue_search_input">
35             <input type="button" id="tipue_search_button" value="Search"></div>
36             <div id="tipue_search_content"></div>
37     </section>
38 
39     </div> <!-- end of page div -->
40     {% endblock content %}

7. Copy it across

The next thing to do is to make sure that we copy the files across:

# Template pages - static pages that use Jinja - relative from content
TEMPLATE_PAGES = {'pages/resources/vim.html': 'resources/vim.html', 'extras/search.html': 'search.html'}

8. Link it into the top page

Check that we've put the link in the top of the page by editing your pelicanconf.py. In the MENUITEMS mapping add your search page:

MENUITEMS = ( ('Archive','/archives.html'), ('Search', '/search.html') ,)

9. Style the search page

The default style for the page is fine, but I did some tweaks to make it a bit more in keeping with my sites look and feel. You can find Moparx's CSS or the Tipue CSS I did to see what's possible.

Tipue search is an easy no-hassle way of getting search set-up for your static site, in this case my Pelican blog. It may not have all the frills of a full server search capability, but it doesn't have all the hassles either. If you do use it on your site it's worth tipping your hat to the developers by buying support which is only 30 GBP.


Posted in Pelican Saturday 19 April 2014
Tagged with blog pelican