Feb 25, 2016
• how-to
• code, blog, javascript, comments
This is probably already on the internet, but I’ll just go over how to add Disqus comments to a Jekyll blog.
First step… Sign up for Disqus! You can sign in with Facebook, Twitter, or Google if you so desire, so that’s pretty cool.
Next thing to do is to Register your site with Disqus, so click on the settings cog, “Add Disqus To Site.” Start using Engage or whatever, go through the registration steps, and select Universal Code whenever you get to that step.
Now for the fun part! Grab the code Disqus gives you and throw that in _includes/disqus-comments.html. Then just use a Liquid include tag.
[sapslaj@sapslaj-desktop sapslaj.github.io (master)]$ touch _includes/disqus-comments.html
[sapslaj@sapslaj-desktop sapslaj.github.io (master)]$ out _includes/disqus-comments.html
<divid="disqus_thread"></div><script>(function(){// DON'T EDIT BELOW THIS LINEvard=document,s=d.createElement('script');s.src='//sapslaj.disqus.com/embed.js';s.setAttribute('data-timestamp',+newDate());(d.head||d.body).appendChild(s);})();</script><noscript>Please enable JavaScript to view the <ahref="https://disqus.com/?ref_noscript"rel="nofollow">comments powered by Disqus.</a></noscript>
[sapslaj@sapslaj-desktop sapslaj.github.io (master)]$ tail _layouts/post.html
<divclass="meta">
{% include post-meta.html post=page %}
</div></header><section>
{{ content }}
</section></artcle>
{% include disqus-comments.html %}
That’s pretty much it. Disqus makes it really easy to integrate their platform with your site, even without any sort of backend CMS. You can leave off the Disqus configuration code. It’s dead simple.
For those who are unaware, MiniTest::Spec is a spec framework that intends to compete somewhat with RSpec. It’s main benefit is that it’s very simply implemented and doesn’t require the same kinds of complexity to achieve a similar result. That still doesn’t mean you should just carry on doing it the RSpec way.
What’s wrong with the RSpec way?
I’ll admit I haven’t read through The RSpec Book, but I have researched enough about testing to know that I believe the RSpec way is flawed.
The issue is that RSpec is trying way too hard to be plain English
Correct use of describe and context blocks as well as meaningful spec descriptions are fantastic and I completely agree with using them. But RSpec tried too hard to be plain English that it ultimately makes tests less maintainable.
Let’s take a look at some examples from Better Specs:
This example pretty much sums up what I’m saying. I should note that this code is verbatim but the real-world implementation would actually require a let or before to set up the context. Here’s how I would implement the same thing:
It probably seems similar to what Better Specs is saying not to do, but their example is very biased:
By combining the context and spec descriptions into one block, it saves one level and makes maintaining that test easier. Secondly, instead of trying to process the DSL and wondering if you need to use is_expected, expect, or should, simply use an assert. asserts are very simple. If whatever you pass to them evaluates to true, they pass. Else, they fail. You can even use MiniTest::Spec’s matchers for a more DSL-ish without going too crazy:
You might go crazy saying there’s duplication or something there. But the thing is, you are providing a plain English description of what it should be doing, then testing that with plain, little magic, Ruby.
But wait, Test::Unit, you aren’t off the hook yet
The plain English thing goes both ways. Test::Unit doesn’t try hard enough. Having everything as plain Ruby classes and methods is fine and dandy until you get shit like this:
Yes, I pulled that from a very popular library using Test::Unit.
Really the only pro to this approach is that I find it easier to translate a programming language to a thought when using simple constructs and not some complicated DSL with so much magic it belongs at Hogwarts.
Bottom line
Using strings to define the test gives you freedom to use plain English, punctuation and all. It separates logic from metadata. It’s a good thing.
Using simple constructs like assertions and expectations make it easier to write as well as read tests.
As you probably are aware, this blog is hosted on GitHub pages and is powered by Jekyll. It provides an interesting challenge when dealing with dynamic content, such as search. Luckily, there is lunr.js, a client-side full text search engine. Sadly there isn’t much good documentation on how to implement it, so I’ll just go over it quickly.
First go grab the JS or Minified JS from the GitHub project or use a CDN and include it in your HTML page. While you’re at it, go ahead and make a search.js file
Now we need to create the lunr.js index.
Of course your setup will be different. As you can see, you can apply boosts to certain fields. Pay attention to the this.ref('id') bit.
Now since I’m deploying to GitHub Pages, I can’t just add in plugins. Therefore I have to do indexing client side, which is fine as long as your blog isn’t Coding Horror. Jekyll has a nifty Liquid filter called jsonify to turn anything into valid JSON. So let’s create a posts.json and utilize that as well as some looping.
Now we can simply get them with a jQuery.get call.
Remember how I said to pay attention to the this.ref('id') bit? Well, Jekyll’s idea of an id is something like /2008/12/14/my-post, and since posts are being stored in an array, it makes finding them a little tricky. Simple fix: use a post factory.
Now you have the basics for client-side search! Still need to work on the view part. For my site, I used Handlebars, but you can use whatever floats your boat.
If you chose to embed the template inside the search page, be sure to wrap it in a {% raw %} block so Jekyll doesn’t evaluate the brackets.
From here, it’s just wiring up the template to an event handler and you are good to go!
Congrats, you now have client side search on your Jekyll blog!
Welp, I did what all of the new kids are doing and switched to Jekyll for my “professional” blog. Still calling it a blag, because edginess. Oh by the way, how do you like the style? I made it myself. :O