Drumknott

Documentation

There are two key parts to using Drumknott on your Jekyll site: adding the relevant Javascript and HTML to have a search form on your site, and uploading your page data to the Drumknott API to ensure your search has results to return.

The Javascript

No matter how you choose to use Drumknott, you'll want to have two Javascript files included wherever you want your search form. The first is perhaps something you're already using: jQuery. The second is Drumknott's own Javascript file (required to allow cross-domain search requests to Drumknott's API).

You'll need to add jQuery to your site if you haven't already, and then add the following to your HTML - probably within your head tag.

<script type="text/javascript" src="/javascripts/jquery.js"></script>
<script type="text/javascript" src="https://drumknottsearch.com/drumknott-0.2.0.js"></script>

Adding a search form

If you don't even want to think about the HTML for the form, the fully embeddable version can be used via some Javascript from Drumknott. Please note that this has an additional dependency on URI.js and, like jQuery, you'll need to add this to your site yourself.

<!-- Put this with your other script tags -->
<script type="text/javascript" src="/javascripts/uri.js"></script>

<!-- Within your body tag, wherever you want the form to appear. -->
<script type="text/javascript">
  search = new Drumknott('my-site-name');
  search.embed();
</script>

Of course, the provided HTML markup and CSS may not be what you want, and the next section covers the minimal Javascript required to connect everything up yourself.

Manually querying the API

If you'd rather create your own form/interface and then make requests to Drumknott's API to populate search results, you can do that using the following Javascript code:

drumknott = new Drumknott('my-site-name');
drumknott.search({query: "keywords", page: 1}, function(data) {
  // loop through data.results - each has name and path values,
  // and display search results as you wish.
});

Uploading page data

As well as having a form sending through search requests to the Drumknott API, you'll also need to send your page data through so Drumknott can return relevant results. This is done via the drumknott gem, which you can add to your Gemfile:

# Gemfile
gem 'drumknott', '~> 0.2.0'

Once this is installed, you will have access to the drumknott CLI tool which allows both saving your credentials locally and uploading your page data:

drumknott keys SITE_NAME SITE_KEY INCLUDE_PAGES
drumknott refresh

The first two arguments for the keys command are your site's name (when you registered it here at drumknottsearch.com), and the generated API key. The third argument, INCLUDE_PAGES, should be either yes or no - it's a flag to indicate whether you want non-blog-post pages to be uploaded as well.

The keys command will save your credentials in a file named .drumknott file to your current directory. Do not commit this file to source control. If you'd rather not have those credentials saved, you can supply them when running the refresh command as environment variables:

drumknott refresh DRUMKNOTT_NAME=SITE_NAME \
  DRUMKNOTT_KEY=SITE_KEY DRUMKNOTT_PAGES=no

And that's it: Drumknott will have stored your page details, and your search queries will now return results. Keep in mind you'll need to run this command every time your site's content is updated.

API

If you want to use the API directly yourself, you're certainly welcome to. There are three endpoints to use:

Updating page details

PUT https://drumknottsearch.com/api/v1/SITE_NAME/pages

You will need to send your site's API key through as the value of the AUTHENTICATION request header, and the Content-Type header should be application/json. The body parameters need to be a JSON object with a single attribute page, which in turn has a JSON object of three attributes:

• name The page's title.
• path The path (without domain) to the page.
• content The rendered content of the page.

This request needs to be made for every page in your site that you wish to be searchable.

curl -X PUT \
  -H "AUTHENTICATION: SITE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"page":{"name":"Blog Post","path":"/2016/01/01/blog-post.html","content":"<h1>Blog Post</h1>"}}' \
  https://drumknottsearch.com/api/v1/SITE_NAME/pages

Clearing existing page details

POST https://drumknottsearch.com/api/v1/SITE_NAME/pages/clear

If you wish to clear out your existing data before updating each page, you can do so with this endpoint. You will need to send your site's API key through as the value of the AUTHENTICATION request header. No body or other headers are required.

curl -X POST \
  -H "AUTHENTICATION: SITE_API_KEY" \
  https://drumknottsearch.com/api/v1/SITE_NAME/pages/clear

Searching pages

GET https://drumknottsearch.com/api/v1/SITE_NAME/pages

This unauthenticated request will return search results for the given query. The allowed parameters are:

• query The search query.
• page The paginated page of results (if not provided, defaults to 1).
• per_page The number of paginated results per page (if not provided, defaults to 20).

The result will be a JSON object with the following attributes:

• results an array of search results as JSON objects with name and path attributes.
• page The paginated page of results.
• per_page The number of paginated results per page.
• pages The total number of pages available for this query.
• total The total number of results available for this query.
• error An error message if your site is not active.

curl https://drumknottsearch.com/api/v1/SITE_NAME/pages?query=pancakes&page=1

Credits

Drumknott was built because I wanted to have a decent search page for my Jekyll-powered blog. The site design is built on top of the excellent work on that blog by Mark Brown, and is open-sourced (so you can submit patches if you'd like).

Drumknott is named after Sir Terry Pratchett's character Rufus Drumknott in his series of Discworld novels. GNU Terry Pratchett.