Setting up Jekyll

Because I’m me, I prefer to install specialized tools like this within their own environment. In this case I’ll use brew+rbenv on OSX to handle it.

rbenv

If you don’t already have it, grab Homebrew to install the dependencies. I checked the version of ruby on my local system with ruby -v to help select the version to install.

mkdir ~/jekyll && cd ~/jekyll
brew install rbenv ruby-build
rbenv install 2.0.0-p481
rbenv local 2.0.0-p481
echo "eval \"\$(rbenv init -)\"" > init.sh
source init.sh
gem install jekyllrb kramdown rouge
jekyll new blog && cd blog

Then add the following section in _config.yml

# Markdown Processors
kramdown:
    input: GFM
    syntax_highlighter: rouge

Create a post

You now have the base Jekyll install available. The next step is to create some content and view it. Create a directory called _drafts to hold content in progress before it’s promoted to an official post.

mkdir _drafts

Then create a new draft post

cat > _drafts/jekyll-rocks.md <<EOF
---
layout: post
title: Jekyll Rocks
---

New Post
========
EOF

Start the server up

jekyll server --watch --drafts

Head over to http://localhost:4000 to see your new install! Jekyll provides a very simple yet robust way to deal with blog or documentation with the added benefit of being available offline, in a browser or not, and fully backed in version control. Win, win, win.

So by now you are probably thinking “Wow, this is pretty cool… if only I could search my blog posts!”. Turns out there is a solution for that. Some use external, free index services while other solutions use local javascript-y solutions. Since I want my content available completely offline, I choose the latter. Jekyll Lunr JS Search proved to be fairly simple to implement and satisfied all my requirements.

Install and configure search

You’ll find excellent documentation in the project readme but I’ll go ahead and burn through the steps I followed here. If you exited the shell be sure to source that init.sh script we created in the first step.

cd ~/jekyll && source init.sh
cd blog
gem install jekyll-lunr-js-search
echo "gems: ['jekyll-lunr-js-search']" >> _config.yml

Now to implement a search box and the appropriate javascript in the default templates. I’ll post the diffs for easy use.

index.html

--- index.orig	2015-07-24 21:50:51.000000000 -0500
+++ index.html	2015-07-24 22:06:06.000000000 -0500
@@ -4,6 +4,13 @@

 <div class="home">

+  <section id="search-results" style="display: none;">
+    <p>Search results</p>
+    <div class="entries">
+    </div>
+    <hr />
+  </section>
+
   <h1 class="page-heading">Posts</h1>

   <ul class="post-list">
@@ -20,4 +27,29 @@

   <p class="rss-subscribe">subscribe <a href="/feed.xml">via RSS</a></p>

+  <script src="/js/search.min.js" type="text/javascript" charset="utf-8"></script>
+  
+  <script id="search-results-template" type="text/mustache">
+    {{#entries}}
+      <article>
+        <h3>
+          {{#date}}<small><time datetime="{{pubdate}}" pubdate>{{displaydate}}</time></small>{{/date}}
+          <a href="{{url}}">{{title}}</a>
+        </h3>
+      </article>
+    {{/entries}}
+  </script>
+  
+
+  <script type="text/javascript">
+    $(function() {
+      $('#search-query').lunrSearch({
+        indexUrl: '/js/index.json',   // Url for the .json file containing search index data
+        results : '#search-results',  // selector for containing search results element
+        entries : '.entries',         // selector for search entries containing element (contained within results above)
+        template: '#search-results-template'  // selector for Mustache.js template
+      });
+    });
+  </script>
+
 </div>

_includes/header.html


--- header.orig	2015-07-24 21:53:17.000000000 -0500
+++ header.html	2015-07-24 21:53:59.000000000 -0500
@@ -19,6 +19,11 @@
           <a class="page-link" href="{{ page.url | prepend: site.baseurl }}">{{ page.title }}</a>
           {% endif %}
         {% endfor %}
+      <div id="search">
+        <form action="/" method="get">
+          <input type="text" id="search-query" name="q" placeholder="Search" autocomplete="off">
+        </form>
+      </div>
       </div>
     </nav>

_includes/head.html

--- _includes/head.orig	2015-07-24 22:17:12.000000000 -0500
+++ _includes/head.html	2015-07-25 11:51:30.000000000 -0500
@@ -7,6 +7,7 @@
   <meta name="description" content="Setting up Jekyll">

   <link rel="stylesheet" href="/css/main.css">
+  <link rel="stylesheet" href="/css/search.css">
   <link rel="canonical" href="http://jaredtrog.com/2015/07/25/jekyll-install.html">
   <link rel="alternate" type="application/rss+xml" title="localhost" href="http://jaredtrog.com/feed.xml" />
 </head>

css/search.css

#search {
    float: right;
    padding: 0px 0px 0px 10px;
}

Wrapping up the install

Go ahead and reload the server with a ctrl+c and jekyll server --watch --drafts, reload http://localhost:4000 and look for the search bar up in the top right-hand corner.

To recap, when you want to work on the blog, cd ~/jekyll && source init.sh to get the environment set up then cd blog and go to work! Be sure to check out the great Documentation at jekyllrb.com.

Okay, now Jekyll has been installed, configured, and we’ve added search functionality! Coming up in another post I’ll share the small wrapper scripts I wrote to simplify the creation of a new post.