I am a happy user of Jekyll. If you are not familiar with Jekyll, it is a website generator that translates textfiles organized in a specific fashion into deployable websites. I like Jekyll because it offers an easy-to-use interface that hides all the technical details involved in conventional website building. However, for people who are willing to get their hands dirty and write their own style sheets, Jekyll is also highly customizable. In this post, I compile some references that were helpful for me when I was building this site. I hope you will find them helpful, too.

Getting Started

  • The official quickstart guide: Jekyll has a very helpful quickstart guide that walks you through all the basics you need to know to create a working website.

  • Guide on Github Hosting: Now you have a website, you probably want to deploy it somewhere on the internet. One way to do it is to host the website as a Github page, for free!

Customization

  • File Organization: If you are not interested in creating a highly customized look for your blog, you probably do not have to know all that much about how the files are organized. However, if you are interested in writing your own style sheets, or tweaking some existing themes, it will be tremendously helpful to spend a minute and read this.

  • Themes: You can find open-source Jekyll themes here. All you have to do is to download or clone the repo of your desired theme. Super simple. The theme I use is adapted from Steven Miller’s NGVB theme.

  • If you are interested in building upon this theme: Small tweaks like changing background or text colors should be easy to do in css/main.scss. If you want to change some more refined details such as margins of images or size of text boxes, you will have to go to the _scss/ directory and directly change the style sheets.

  • Liquid: As you probably have read in the Jekyll quickstart guide, Jekyll uses a combination of YAML front matter and Liquid to enable some cross reference to posts. An example: in the front matter of post A, you can define a property of A called category with value life. This value can then be referenced in other pages by calling {% A.category %}, where {% ...%} symbolizes a Liquid expression. During compilation, these Liquid expressions will be replaced with their actual values, so they do not appear in the final HTML files. A helpful introduction to the usage of Liquid in Jekyll can be found here. The official docs for Liquid can be found here.

Markdown

  • Markdown cheatsheet: Jekyll supports multiple markup languages, and you can specify the flavor you are using in _config.yml. (I use Kramdown). There are many Markdown cheatsheets online, and a really nice one that I use can be found here.

  • MathJax: What if I want to write equations, you ask?. One way to do this is through MathJax. The quick start guide for MathJax can be found here. You can type equations (almost) the same way you would in LaTex. One thing to note, however, is that, the default configuration I had for MathJax uses $$ ... $$ to denote inline math, and \\[ ... \\] for new-line display, although I think you can customize this if you want.

    • Something to note here is that sometimes the \\ symbol inside the TeX environment does not get interpreted correctly (eg. in the example of using the cases environment). In some of these cases, replace the \\ with \cr solves the problem.

My To-Do List

There are many aspects of my blogging workflow that can be further optimized, and here are some of them.

  • Scripts for easy post management: I find populating the YAML front matter and naming the blog post every time to be pretty annoying. This would certainly be a problem if you blog a lot, and of course people have tried to write scripts to automate the process. One of such attempts can be found here Also, if you use Octopress, there are built-in functionalities that help with creating posts.
  • Vimrc: I use vim as my editor. I feel there are a lot configuration that can be done here to make blogging in Jekyll easier, too.
  • LaTeX: Is it convenient (or possible at all) to typeset in Latex and then use Pandoc to translate into markdown? Haven’t got a chance to try it, but heard some good things about Pandoc.

Conclusion

So, this is it folks. I hope some of the things in this post have been helpful. Happy blogging!