Adding search capabilities within your Pelican-powered site using Tipue Search

The ability for visitors to quickly find what they are looking for on a website is pretty important. It can mean the difference between them staying on your website or leaving to find what they are looking for elsewhere.

With static website generators like Pelican the first options that come to mind are generally pointing a user to the website's archive or using an embedded search box linked to a major search engine with a parameter to display only links from your website.

However, those two choices are not always the best course of action. Websites can have a rather large archive page which visitors aren't really going to want to wade through and using a search engine's search box simply sends them off-site to find what they are looking for which not a really the best way of doing things.

Tipue Search, an open source site search engine jQuery plugin available under the MIT License, is an elegant solution to this problem which allows you to easily add proper search functionality into your website.

Getting Started

Prerequisite: Install BeautifulSoup on your computer if you do not already have it installed.

pip install beautifulsoup4

It may also be in your Linux distribution's repositories as well. For example, it is available as python-beautifulsoup4 within Arch Linux's community repository.

With the prerequisite out of the way we can begin downloading the files that we need.

  1. Download Tipue Search and extract the contents into your theme's static directory (themes/<your_theme>/static/tipuesearch/).

  2. Download the Tipue Search plugin from Pelican's Git repository and place it in your plugins folder. If you do not have a plugins folder, you can simply create one. We will point Pelican to that directory so it can be used in our next step.

  3. Edit Pelican's configuration file (pelicanconf.py)

In order to load the plugin you will need to specify the location where your plugins are stored and which plugins that you want to use. Assuming this is the first time you have used plugins with Pelican you should add something similar to this:

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

Note: PLUGIN_PATH can be the absolute path to the plugin directory or the path relative to your settings file.

Next you want to add the DIRECT_TEMPLATES setting listed below. This setting tells Pelican which templates are to be used directly to render your content. If you don't add it, it will not render the search.html page.

DIRECT_TEMPLATES = (('index', 'tags', 'categories', 'authors', 'archives', 'search'))

If you already have this setting in your configuration file, you simply need to append "search" at the end.

Editing Templates

Open the base.html template file and add the following within the <head> section of the page. I would recommend putting it under the line for the main CSS file.

<link rel="stylesheet" href="{{ SITEURL }}/theme/tipuesearch/tipuesearch.css">

Within the same template, add the following code where you want the search box to be placed. I personally put mine in the navigation bar.

<form id="searchform" action="/search" onsubmit="return (this.elements['q'].value.length > 0)">
    <input id="searchbox" type="text" name="q" size="12" placeholder="Search">
</form>

Next, add the relevant CSS to your main.css file and adjust it to fit your site as needed.

#searchform { float: right; margin-top: 10px; }

#searchbox {
    background-color: #F5F4EF;
    border: 1px solid #F5F4EF;
    border-radius: 4px 4px 4px 4px;
    -moz-border-radius: 4px 4px 4px 4px;
    -webkit-border-radius: 4px 4px 4px 4px;
    height: 10px;
    padding: 4px;
    margin: 0px 15px;
    vertical-align: top;
}

Finally, create a template called search.html and paste the following into it:

{% extends 'base.html' %}

{% block title %}
Search - {{ SITENAME|striptags }}
{% endblock title %}

{% block content %}
<script type="text/javascript" src="http://ajax.googleapis.com/ajax/libs/jquery/2.0.0/jquery.min.js">
</script>
<script type="text/javascript" src="{{ SITEURL }}/theme/tipuesearch/tipuesearch_set.js"></script>
<script type="text/javascript" src="{{ SITEURL }}/theme/tipuesearch/tipuesearch.min.js"></script>

<script>
$(document).ready(function() {
     $('#tipue_search_input').tipuesearch({
         'show': 10,
         'mode': 'json',
         'contentLocation': '{{ SITEURL }}/tipuesearch_content.json'
     });
});
</script>

<section id="content" class="body">

<div align="center"><input type="text" size="60" id="tipue_search_input">
<input type="button" id="tipue_search_button" value="Search"></div>
<div id="tipue_search_content"></div>

</section>
{% endblock content %}

Finalizing

Once you have saved the files, regenerated your website, and uploaded the changes you should have a working installation of Tipue Search on your Pelican-powered website.

So, how does it search your website? The tipue_search Pelican plugin that you installed generates a JSON file called tipuesearch_content.json which stores the content of all your posts. When a search is issued, Tipue Search reads the JSON file and quickly and seamlessly outputs the search results to your visitor.

If you are interested in learning how to tweak Tipue Search's configuration, please read the Offical Documentation.

Additionally, If you use Pelican's default theme called "notmyidea", please feel free to use my tipuesearch.css file which matches the theme.

Comments?

recommended sites

social