Help With Jekyll

Jekyll is a parsing engine bundled as a ruby gem that is used to build static websites from dynamic content like templates, Liquid code, and markdown. Jekyll makes it possible to add posts to a blog without having to keep adding each new post to the archives. Because Jekyll websites are static, they load quicker than sites that must constantly communicate with a server. Also, Jekyll-based websites are extremely secure.

Getting Started:

I recommend going through The Ultimate Jekyll Tutorial to gain an understanding of how Jekyll works. My classmate, Tony Leung, also wrote a great post about this here.

Some Challenges You May Face

The following resources and suggestions may help with some common challenges you might face.

If you need help hosting project pages on Github: It is easy to host a page in your username.github.io repo. But what if you want to save a project page in another repo? Visit this resource for help setting up project pages. The URL to open a project page will be username.github.io/PROJECTFOLDERNAME/FILENAME.

If gitgnore isn’t hiding the _site folder: visit this resource.

If your Jekyll project won’t upload properly: the problem may be that you are using plugins in your project. Github doesn’t allow for plugins to be uploaded, primarily due to security reasons. You can either upload your project on another server (i.e. AmazonS3) or remove the plugins. In my case, I tried to use a single Liquify command and a plugin to access all stylesheets. Manually linking to each stylesheet in the base html page resolved the problem.

If your blog index isn’t working unless it is on the index.html page : if you want your blog index to be on a page other than index.html (i.e. username.github.io/blog/) create a folder called blog in your root directory and put a file called index.html inside it. Note that if you create a file called name.html inside your root directory, the name of the file will be converted to a folder name inside the _site folder and the name.html will appear inside the blog folder as index.html. Move your _post folder inside your blog folder. Then, change the paginate path in your configuration.yaml folder to something like blog/page:num. This may not completely solve the issue of the blog pagination not appearing. For more help, consult this resource.

If you are seeing a bunch of liquid tags instead of your content when you open index.html This is normal. You won’t actually see your content or formatting until you run your project on a server. Type jekyll serve in the command line and open the URL that will appear in your browser. If your CSS still isn’t working, make sure you are specifying the right file path in your html document.

If anyone is having difficulty with Jekyll, feel free to contact me and I will try my best to help!