Thanks to Jekyll, I'm Cheating on WordPress and it Feels Great

It’s OK. Don’t worry. I asked my Rabbi. Well, actually my friend’s Rabbi as I’m not Jewish. I text’d him wondering if this was a “sin.” Yeah, a Rabbi that has a smartphone and accepts text messages. He said to be quick as his wife was making him Matzah ball soup – his favorite. She has this thing where she adds a dab of curry to spice it up.

She says his sermons are so much more interesting on the weeks she adds curry to his soup. Not a congregant can be caught sleeping, during those weeks. Well, the short answer is, he said, cheating only applies when you have a relationship with a woman outside of your marriage. He said I wasn’t married to WordPress, so there was no concern. He’s one smart Rabbi.

I think we’ve all thought about it, right? “Cheating” on WordPress. I’ve had a wondering eye for a while now reading reviews of other CMSs and blogging platforms. There are tons of them out there. Of course, if you are a blogger, they are the 800lb gorilla. They’ve been around for a while. I’ll save you the trouble of reading this post though.

If you are a typical blogger using WordPress, my suggestion would be to stay with WordPress. WordPress is both very powerful and fairly easy to use – Blogger might be a “bit” easier, but WordPress sites are especially beautiful and have real polish.

So those reading this blog, you might have noticed that this site looks like a WordPress blog.  And it is.  See I have a few blogs.  This blog is more of a programmer and tech general interest blog – mostly words.  My other blogs are either promoting my open source projects or business and have lots of code and/or math on them.  It’s all about having the right tool for the job.  So, what site do I have on GitHub using Jekyll?

Well I have two, but the one I will be discussing is my programming homepage James Lavrenz, which uses the Poole framework (called the Jekyll butler) with the Lanyon theme – links to follow. I opted for a clean and minimalist look. This post covers how I set up my homepage with the intent to show other programmers how to set up a programming blog on GitHub (again using Jekyll).

(So back to the program.)

WordPress has tons of creative-types developing themes that are so pretty – Iggy Azalea pretty. That has always been one of the things about WordPress that I’ve always liked. That is, the creative-types often were there doing what creative-types do. Creating gorgeous sites and themes. Well, devs have been a big part of making WordPress what it is, too. WordPress has so many plugins – 37,120 do be exact. That’s a lot of plugins.

But, if you are a dev and doing some blogging about your open source code, things change. For one, WordPress caters to traditional writers IMO. Markdown and other things are more recently supported, but their focus has always been on a more traditional blogger – mommy, foodie and fashion bloggers, etc. (Just look at the sites that get so-called Freshly Pressed – very few are about programming.)  When I say programming, I mean code-based programming blogs, not a blog like the one you are reading.  (I have no intention of showing code or doing math on this site. That’s a great way to lose readers!)

Sure there are lots of serious code-centric programming blogs hosted on WordPress, too (self-hosted or WordPress.com), and those people likely jumped through a few more hoops to make it look sweet if they are showing code and/or math. (Although note: if you like MathJax, fuhgeddaboudit with regards to WordPress.com – they no likey you to have JavaScripty stuff on their servers. Bastards!) Actually they have a good reason to not allow this, but I’m not telling (it would bore you and you would leave).

One hoop or hurdle is the TinyMCE WYSIWYG editor (common to many open source CMSs, etc.) might just eat your code if you aren’t careful. When I say eat your code, I mean things like stripping characters and stuff. If you were wondering, I use the word to “stuff” to be all folksy. Under the hood, I am a Vulcan, and my algorithm requires I use that word at times.

The comment in the algorithm says humans like words like “stuff,” the utterance “hum,” and adjectives as they are emotional creatures, not logical Vulcans. Humans are also stupid and think the Oxford comma should be optional. Why? It’s the world’s easiest grammar rule. So I’m programmed to always use the Oxford comma just to piss humans off. What are you gonna do about it? One of YOU geeks programmed me.

(Back to reality…)

So, you have to make sure you are in text mode when you paste in code (don’t be in visual mode). And make sure to select “Paste” to paste it in and not “Paste as Text.” The latter option is only to be used if you are pasting stuff from an HTML webpage. It then strips stuff out for you – in this case a good thing. It took me a while to figure that out. I guess I could’ve read the docs. But like most, I didn’t.

Reading docs is a good way of trying to cure your insomnia though. Also, moving back and forth between text mode and the visual editor can be a recipe for disaster, too. This is especially true if you don’t just have code but LaTex for math in your post as well. LaTex is full of backslashes that scares the TinyMCE editor. It might respond by stripping them out and creating a real havoc. Ouch.

So my point is if you want to do a hard-core programming blog with code and/or math, you probably will find it easier on GitHub!  (Or others like it that focus on markdown and allow MathJax.  MathJax is prettier than using images IMO. Just an FYI, MathJax works fine on WordPress self-hosted.)

I also tried the markdown feature of WordPress (a fairly new feature of JetPack), but it didn’t seem as “standard” as what GitHub uses. I like kramdown, an option on GitHub, because it works better with MathJax. So I decided to try Jekyll. I’ve noticed every coder out in the wild, even the Neanderthals like me, were using GitHub. I almost forget there was version source control thingies before GitHub (of course Git is the engine under the hood).

Centralized version control is the Edsel of version control. Well, it has its place, but those places are shrinking. Open source is where it’s at, and distributed version control, like Git, is the Maserati. Like using Vim, having an master’s degree helps. Actually Git is not that hard, but I read when it first hit the streets, it was a challenge to use. Of course, it was written by a guy (demi-god Linus Torvalds) probably with an IQ of 200. So what did you expect?

Back to your regularly scheduled program… Jekyll. This was produced by one of the founders of GitHub Tom Preston-Werner - Blogging Like a Hacker. It produces static sites. Hence, they are screaming fast – and secure. It is written in Ruby and very easy to configure and change. Since you write your code in your favorite text editor, no worries that your code will be eaten or mangled. Backup and version control is done with Git and GitHub.

You don’t have to use GitHub, but if you do, you can even host your site for free on their server – well not THEIR server as I think they host it on Rackspace? They even use a CDN, so it is fast. Again, all free – no charge even for domain mapping, too, if you have your own domain name. No need for your own shared hosting if you use GitHub.  To be honest, WordPress.com renders images faster in my experience.  In fact, even my former GoDaddy shared hosting account seemed faster when it came to images.  This is also why I chose WordPress.com for the blog you are currently reading as I wanted to have large images on the site.

(WordPress powers about 20% of the Internet, and the backbone of WordPress.com is solid. They even have a VIP option for businesses, so it has to be stable.)

I have five computers (and I code and write from all of them at times – cuz I’m cool), so here is the typical process I use when doing a blog post. Before I write one word, I do a git pull. When I am done writing on that particular computer, I do a git push. Simple. (I hope it was clear my changes were committed first!)

Using this process ensures I can work on all five computers without a hitch. No thumb drive or emailing of files required thanks to GitHub. Oh, if you think GitHub is evil (not sure why but let’s run with that), you can host it on your own server, too – just like any static HTML site. And since it’s static HTML files, it will be super fast.

When it comes time to styling your blog. You can use many of the open source themes. I went with the Lanyon theme. It’s a pretty and minimalist theme. If it was a girl, it would be Jennifer Lawrence without makeup – sweet. To throw some chum to my female readers, it would be Bradley Cooper if not the fairer sex.

So, I added some stuff like an Archive, Google Analytics, Custom Google Search, Disqus for commenting as well as the typical social-share buttons. (Update: I only left in Google Analytics, but the files are still in the include folder in case you want to use them.)

So, you want to have your own domain name? You can do that too. I just followed the GitHub guides here: GitHub support regarding GitHub pages.

If you don’t bother getting a domain name, your address would look something like mine (where jameslavrenz is my username on GitHub).

http://jameslavrenz.github.io

You can even set up GitHub pages for each project, not just your username. It requires an extra step that is covered in the GitHub support link above. What better way to promote your open source project than to have its own dedicated page or website.

Where to Start

Start here to install Jekyll then download your theme from GitHub (I used the Poole framework with the Lanyon theme). Copy the theme over to your newly created repo (in my case jameslavrenz.github.io). Update the yml (yaml) config file. If you clone my repo, just remove the Google analytics code in the include file as well as any other hard-coded stuff related to me like Google authorship or social links, etc.

Then start blogging! Posts go into the _posts folder. Just follow the example posts as there is something called front-matter that you will need to have in the top of each file. It will feel like you are coding as you will be using Vim/Notepad++/TextMate/gedit/MarkdownPad2 or whatever your favorite editor is.

Your blog will be at

http://your_user_name.github.io

Also check the resources I listed below. I found the first tutorial to be very helpful, and I used his archive page from his repo. FYI, technically you don’t need Jekyll as GitHub rebuilds your site when it’s pushed to GitHub. Also note you can’t use plugins with Jekyll if you plan to host your site on GitHub pages.  There is a way to do it, but it is beyond the scope of this post as it’s more involved.

My homepage and code-centric/math programming blog is on GitHub pages using my own domain name. I’m very happy with it. If you are a hacker, I think you will too.

Happy Jekyll’ng!

UPDATE: I removed Disqus and Google Custom Search but still have them in my GitHub repo for this site – in the includes folder. If you clone this repo, make sure to replace my Google Analytics tracking code with yours – it’s hardcoded in the include file.

Additional Resources

Share: