Jekyll

Jekyll produces very nice looking results, but setting it up can be a pain. Here are a few things I’ve learned.

1. Github Pages doesn’t support most themes

To see a list of all the supported themes, go here. If you really want to use an unsupported theme, you can render it out to _site and then push that.

2. Using GitHub Pages themes locally

Put gem "github-pages", group: :jekyll_plugins in your Gemfile, then do bundle install. You can then run your server with bundle exec jekyll serve --safe. Running it without bundle exec probably will not work, because your site needs the github-pages gem. --safe makes jekyll ignore symbolic links and disables custom plugins. Github pages uses the --safe option when generating your site, so you should make sure it works with that option.

For more information about setting up GitHub Pages, go here.

3. Hacking the themes

You can modify colors, etc. by editing assets/css/style.scss. Put the following at the top:

---
---

@import "{{ site.theme }}";

Then put any css you want below it.

It took me forever to get this to work for some reason. Part of the problem was that my file was named style.css instead of style.scss. That will cause anything you put in it to fail without giving an error of any kind.

Other tips

• Make sure to do jekyll serve from the root of the project, otherwise weird stuff will happen, including a _site directory being generated in the directory you’re currently in. I don’t know why jekyll lets you do this. Don’t do it.
• Any files you want to include using {% include foo %} have to be placed in _includes.