I have had some pretty big changes going on in the last few months: new career, new hometown, but most importantly, new website! Over the last month I’ve taken my php website and switched it over to a Github Page powered by Jekyll written in HTML and Markdown. I made the big switch because I wanted a platform that would be easier for me to write blog posts. Although other blogging platforms have a lot of UI tools that are created to make blogging easy, I found myself more often than not fighting with the tools. All that changed when I was shown knitr. Needless to say, I am a convert. I plan on writing an introduction post to knitr in the next few months, but in the meantime back to Jekyll and Markdown.
What is Jekyll?
From the creators, “Jekyll is a simple, blog aware, static site generator.” What does that mean to me? It means a way for me to have an integrated blog within the framework of my current website. It also means a universal template frame work that my whole site is now built upon. Jekyll takes a template and runs it through Textile or Markdown and Liquid converters and spits out a static web site. This led me to using Markdown as the primary tool in revamping my site.
What is Markdown?
Markdown is a lightweight markup language that allows users to use easy to read and easy to write text that can then be converted to HTML. Luckily, Github already has a Markdown interpreter built in, making my life even easier. In my opinion, Markdown is all the functionality of HTML with half the syntax. Creating a blog post in Markdown is not much different than jotting down my thoughts. I don’t need to worry about HTML tags or rich text formatting headaches (like I did with WordPress).
While everything is unicorns and rainbows now, there were some bumps along the way and I’d like to document those for posterity.
There were three main aspects of my site rebuild that I would classify as tricky. Two of these have to do with blogging and were solved by the same fix. The third is related to creating an entire site using the Jekyll framework.
Math Equations and R Code Display
When writing blog posts I (obviously) want to have the ability to display LaTeX style equations and display R code with syntax highlighting. Luckily for me, this functionality is included in R flavored Markdown. Unluckily for me, Jekyll has its own way of rendering R code that prevented things from working out well. After spending a few week grappling with this problem I finally went to the genius Himself (Yihui) and he pointed me down the right path. He had already created a way to render code for highlighting by Jekyll! So, if I want to display code or equations I simply need to add the following to my posts:
Simple as that, my problem was solved!
My other main problem comes from trying to have my whole site utilize the Jekyll templates. I wanted to run each page off the same template so that I didn’t have to change every page when I had to edit one thing. This seems to work with the Jekyll templating idea, except for menu item highlighting. You see, when you go to a page on my site, that menu item is highlighted (see above). Now, with every site running from the same template, how to make that highlighted dynamic? There are a couple steps to this process. The first is creating a navigation in your _config.yml file (from the Jekyll installation). For me, this amounts to adding these lines:
Then, in my template file where my menu items used to be, I added this:
You’ll notice that instead of having static menu tabs, I now loop through the links in the site navigation in my _config file and add class=current if necessary. Also note the use of Liquid syntax that Jekyll is compatible with. And finally, in the header of my posts, I add:
This allows for the posts to keep the Blog menu item highlighted.
That’s it! I hope you find these little tips to be useful, I sure did! I look forward to regularly updating you on my new blog platform!
blog comments powered by Disqus