Jekyll pages on GitHub: how does it work?

Question

I have my gh-pages branch for my project and trying to create some documentation for it. On GitHub I've read that every time I push things onto the GitHub server, the page is actually fed through to Jekyll.

I haven't installed Jekyll locally. For now, I just want to use GitHub's, and essentially act as a "user".

But... how does it actually work? I've created a .markdown page and saw that the equivalent .html is created and marked up, like this:

---
title: This will be used as the title-tag of the page head
---

Now, let's see.

# Is this working?

But... how do I find out how to actually use Jekyll?

I am aware of http://jekyllrb.com/docs/ but I still can't quite figure out what else I can do, and -- more importantly -- how to simply place a markdown file that will be "templated" with the current template?

Thank you!

Answer 1

There are several problems here:

1. You need to install Jekyll locally. It's not hard to do, and it makes life a lot easier. Follow the instructions on http://jekyllrb.com.

2. Your .markdown file needs to go in your site's _posts directory for Jekyll to transform it into a post. Any files that begin with YAML front matter (the stuff at the top of the file between the dashed lines) are also processed.

3. In order to use a layout, you need to metion it in the page's YAML front matter. So if you changed the example above to:

---
title: This will be used as the title-tag of the page head
layout: default
---

Then this page would be generated with the template called default.html in your site's _layouts folder.