How to Setup Jekyll with Google Plus Comments on Github Pages

21 February 2016 on . 11 minutes to read

Why migrate to Jekyll?

I’ve had my website set up on Wordpress for the last month. I spent roughly 13 hours setting the site up, with the break down as follows:

  • Install and configure wordpress on Digital Ocean: 30 minutes
  • Research what plugins are needed to nicely manage what’s going on, get markdown for posts: 2 hours
  • Read up on configuring wordpress settings for optimal SEO: 2 hours
  • Finding out that all the plugins I’d researched are currently freemium and you have to install a second set of plugins to add on functionality that used to be free and configuring those plugins to work with the first and not override each others settings: 6 hours
  • Work with different Wordpress themes to find something simple and clean that wouldn’t make your eyes bleed after a long post: 3 hours

After I decided to change themes a few days back, it hit me today that it was all a massive waste of time. It didn’t help that I’m new to wordpress, but taking a couple hours every time I wanted to clean up my site or add a little functionality? Forget about it. Especially when most of what I do is in rails, and when you need to complete some banal task in Rails, you can just search for some gems. Daniel spent some time last week praising Jekyll, so it was fresh on mind and I knew going into it that it take care of many of the problems I had with Wordpress. Namely that my goal in life isn’t to become a Wordpress expert, but to simply code away, and then post my experiences with the minimal amount of added effort.

Jekyll and Github Pages

Jekyll is an open sourced, ruby based blog gem that, quite simply, kicks ass. So, why does it rock?

  • Write posts in markdown
  • Extremely easy to customize
  • Custom functionality via ruby
  • Integrates with (Github Pages)[https://pages.github.com/]

I’m a huge fan of having control over what I do, which is a big reason I keep most of my apps deployed on Digital Ocean1 rather than a managed server. I may deploy this Jekyll blog to my own server in the future, but letting Github host it is the easiest thing in the world. Github Pages details how to set it up. Prepare to have your mind blown, the following is all you do:

  • Create [username].github.io repository on your github account.
  • Clone the repository, or a theme of your choice
  • Make sure origin points to the repo you created earlier
  • Push to repo

Know how to git commit and git push. Yes, that’s literally all you have to do to make it work out of the box. I’ll detail the full steps in the next section, but my full time for deploying Jekyll is as follows:

  • Find theme I like, clone it: 5 minutes
  • Create github repository with correct name: 1 minute
  • Change origin of cloned theme to point to my repository and push: 1 minue
  • Setup background image and avatar: 1 minute
  • Customize slugs and publishing paths for posts: 10 minutes

Yes, 18 minutes total. It looks better than any of the wordpress sites I ran across, especially considering that digging through the wordpress themes CSS files and using Chrome inspector takes ages compared to editing a bootstrap based theme. This is extra true if you develop sites with bootstrap on a regular basis, which is very likely for Rails types, so you’re already familiar with the changes you need to make. Combined with my personal dislike of php and how clean the jekyll project organization is out of the box, I’m ready to declare that going this path has been a huge win, and as I write this my jekyll site’s only been up for a few hours.

Jekyll Settings and Customization

The following are some configuration changes I highly recommend; some of them are specific to migrating from a previous blog.

Sitemap

If you’re not already, you need to have your site on Google’s Webmaster Tools. If you’re transferring from another blog, ensure that the registered sitemap is pointed to your new sitemap url. Typically yoursite.com/sitemap.xml. Additionally, add your Google Analytics code to includes/_footer.html.

Front Matter

Adding a yaml block like the following to the BEGINNING of a post will add post ‘variables’ that can be accessed by Jeckyl. For example, the following code overrides post.title and also sets the layout to use the post layout. You can also set custom attributes if you really want to customize your page.

---
layout: post
title: How to Setup Jekyll with Google Plus Comments on Github Pages
---

Maintain Structure

For SEO purposes, ensure your old links are hosted at the same url. Only do this if your old links are properly slugged, and not prepended with extra characters. Wix, for example prepends special characters to the slugs, which kills SEO. If your old links aren’t slugged properly, then don’t worry, Jekyll takes care of that for you. If you DO have a post that’s ranked well on google, then it’s in your best interests to either set a redirect for that post URL, or maintain the old post and a canonical link to point towards where your new post lives:

<link rel="canonical" href="http://[yoursite]/[new-pretty-url]" />

For SEO purposes, I prefer using only the post’s title in the slug. The following attribute in _config.yml takes care of this:

permalink: "/:title/"

Custom DNS

Also extremely easy. After creating a CNAME on your registrar that registers your desired domain to point to [username].github.io create a file called CNAME in the root directory of your project, check it into git and add a line with the url of your desired and registered domain name. For this site, my CNAME file contains:

blog.nrowegt.com

Short, sweet, functional.

Excerpts

My preference is when you visit the site, you see excerpts from each post. Jekyll has this functionality built in. Just make the following changes:

_config.yml: excerpt_separator: "<!--more-->"

index.html: {{ post.excerpt}}

This tells Jekyll to only put content that comes before the <--!more--> tag into the index. I also use this mixin for my RSS and Atom feeds. It helps people navigate recent posts easier and also allows you to track who’s reading your full articles instead of just hitting your homepage and clicking out.

Issues Encountered

Jekyll-Paginate

The first time I tried jekyll serve I got hit with the following:

Dependency Error: Yikes! It looks like you don't have jekyll-paginate or one of its dependencies installed. In order to use Jekyll as currently configured, you'll need to install this gem. The full error message from Ruby is: 'cannot load such file -- jekyll-paginate' If you run into trouble, you can find helpful resources at http://jekyllrb.com/help/!

After a few minutes of searching, bundle update calls for various gems and some rbenv rehash action, it dawned that this is pretty similar to Rails errors complaining about incorret versions installed, even when a bundle show [gemname] shows the correct one. bundle exec jekyll serve took care of the issue.

Apostrophes rendering as ’

Apostrophes should work, no need for escaping them. I ran into this issue on some pages; it ends up that because of alterations to where I had my posts being served, they weren’t associating the post layout with them. Adding the following to the top of each post solved this issue, since the post layout forces UTF-8 encoding in the html doc.

---
layout: post
---

Fenced Code blocks rendering a single backtick style code blocks.

The following examples show the two styles of codeblocks you use with markdown. The single backtick and the triple backtick.

example of single backtick block

def triple_backtick_example
  puts "Code fencing."
end

As I created this blog post, I noticed some codeblocks rendered incorrectly. They looked sloppy, and triple backtick blocks weren’t picking up syntax highlighting, even when specified. I ran across this post which gave a fix. Apparently Jekyll’s default markdown renderer has this issue. Specifying markdown: redcarpet in _config.yml solved the problem. Now they’re properly fenced and highlight correctly as well.

UPDATE After deploying the above to Github Pages, I received an email with the following:

You are currently using the 'redcarpet' Markdown engine, which will not be supported on GitHub Pages after May 1st. At that time, your site will use 'kramdown' for markdown rendering instead. To suppress this warning, remove the 'markdown' setting in your site's '_config.yml' file and confirm your site renders as expected. For more information, see https://help.github.com/articles/updating-your-markdown-processor-to-kramdown.

Remove the line specifying redcarpet, and find and replace in your _posts and _drafts directory for all triple backticks to replace them with ~~~ (triple tildes) instead. Problem solved.

Google Plus Comments

Feedback’s not just important; it’s neccessary. An echo chamber of 1 can be great for the ego, but does nothing for professional development. Jekyll ships with Disqus as the default comment engine. I’m a huge fan of Scott Adams of Dilbert fame. Every few weeks he’ll have an issue with getting locked out of Disqus and has commented repeatedly that for unknown reasons, restoring his account access takes days. Not good if you anticipate involvement with commenters. Primarily due to this, I’ve decided to go with Google+ to handle comments for this site. How to add google comments to jekyll. got me started. In the end though, the baseurl: http://[post mount url] line in _config.yml caused issues with my server. Booting it would show it serving at http://localhost:4000/http://blog.nrowegt.com. Going to a straight javascript implementation over HTML5 fixed this. My end result was:

includes/_comments.html

<script src="https://apis.google.com/js/plusone.js"></script>
<div id="comments"></div>
<script>
gapi.comments.render('comments', {
    href: window.location,
    width: '624',
    first_party_property: 'BLOGGER',
    view_type: 'FILTERED_POSTMOD'
});
</script>

_layouts/post.html

</article> {% include comments.html %}

Now you can successfully log in with a google account and comment and +1 to your hearts content.

Escaping Liquid Template Tags

I’ve now gone meta. While writing the above section, I found that liquid tags inside of code blocks actually execute, and allow you to show what would otherwise be injected into the page. This post details the syntax allows you to escape liquid tags.

The above fixes added an extra 20 minutes or so of time on google and local testing. Score an extra point for the Ruby and Jekyll communities.

RSS/Atom Feeds

One quirk I found upon checking the site’s feeds was that upon loading it in Feedly it was listing it as “Sitewide RSS Feed”. Changing the following lines fixed this.

_includes/head.html

<link rel="alternate" type="application/atom+xml" href="http://blog.nrowegt.com/atom.xml" title="NRoweGT: Nathaniel Rowe Atom Feed" />
<link rel="alternate" type="application/rss+xml" href="http://blog.nrowegt.com/rss.xml" title="NRoweGT: Nathaniel Rowe RSS Feed" />

If This Then That

The final step of this has been to integrate If This Then That to the site feed. Wordpress has automation tools for sending new posts to your networks, so I simply pointed IFTTT to my feed, and attached it to my Linkedin and Twitter accounts. Super easy.

Wrap

This has been a comprehensive post on setting up a Jekyll site with Github Pages. I can’t express how amazing it was to get a fully functional setup in probably 25% of the time it took for me to write this post. I’m 100% happy with what I have, and can concetrate from here on out on content generation, not configuration. That’s a major win.

  1. That’s my referal link. $10 discount if you sign up with it. 


If you enjoy having free time and the peace of mind that a professional is on your side, then you’d love to have me work on your project.

Contact or view a list of available services to see how I’ll make your life better, easier and bring satisfaction back into you running your business.