One of the features that made me fall in love with Jekyll was how super simple it was to start a new project. With one command jekyll new project_name you’ve got a brand new Jekyll project to start working on.
Posts
If your new Jekyll project is going to be used for blogging, you’ll want to create posts for your new blog.
Jekyll by default provides a folder in which all your posts live. Within the Jekyll project, you’ll find a folder called _posts. To create a new post you’ll need to create a new markdown file with a file name in this format:
YYYY-MM-DD-title.markdown
The format is four-digit year, followed by a hyphen then two-digit month, followed by another hyphen and two-digit day, followed by a hyphenated title and ending with the markdown file extension.
So for example today’s date is May 29, 2016 and I want to create a new post called I love eating pizza. It would look something like this:
├── _posts
│ ├── 2016-04-06-welcome-to-jekyll.markdown
│ └── 2016-05-29-i-love-pizza.markdown
Now that you’ve got your new post file, you’ll have to add in a few more things before you’re ready to write your post.
Up at the top of your new post file, you’ll have to add in some Front Matter. Front Matter is the stuff you find at the top of posts and pages between a pair of --- triple-dashes. It is written in YAML, also known as YAML Ain’t Markup Language.
If you’re unfamiliar with YAML it is made up of key-value pairs which looks like this:
key: value
At a minimum, a post file should have two keys. A layout and a title key. So for my, I love pizza post, this is what the Front Matter will look like.
---
layout: post
title: 'I love pizza!'
---
The example post file that Jekyll includes in a new project has two additional keys; date and categories. So the Front Matter with these two keys would look something like this:
---
layout: post
title: 'I love pizza!'
date: '2016-05-29 13:25:00 -0400'
categories: food
---
What the date key is used for is to override the date from the post’s file name. So for example if you’ve got two files written on the same day, Jekyll will sort them according to the title of the post.
├── _posts
│ ├── 2016-04-06-welcome-to-jekyll.markdown
│ ├── 2016-05-29-i-love-pizza.markdown
│ └── 2016-05-29-jelly-filled-donuts.markdown
If you take a look at the example at the top, I’ve written another post today about jelly-filled donuts. Even though the donuts post was created after my pizza post, if I don’t define a date in the Front Matter, in reverse chronological order Jekyll will place the pizza post before jelly-filled donuts post.
The format for the date value should be:
YYYY-MM-DD HH:MM:SS +/-TTTT
The format is four-digit year, followed by a hyphen then two-digit month, followed by another hyphen and two-digit day, followed by the current time all in two-digit format, followed by an optional timezone offset. A note about the hours for time is that it needs to be in 24-hour notation.
The categories key is used to tell Jekyll which categories it belongs to. This way you can group related posts together.
Going back to my jelly-filled donuts post, the Front Matter could look like this:
---
layout: post
title: 'Jelly-filled donuts are my favorite'
date: '2016-05-29 15:12:11 -0400'
categories: food
---
By using the same category of food for the jelly-filled donuts post and the I love pizza post, both posts can be accessed on something like a categories page listing all food posts. Or you could include a category link in the metadata of a post which a user could follow and find other posts about food.
Now that you’ve added in the Front Matter for your post, you can start writing the content of the post; which will start after the second set of --- triple-dashes.
---
layout: post
title: 'Jelly-filled donuts are my favorite'
date: '2016-05-29 15:12:11 -0400'
categories: food
---
Jelly-filled donuts are my favorite type of donuts because I like getting them without knowing what's inside of them. I like to be surprised the moment I bite into them :)
Since the post file is of type Markdown, you can write all the content of your post in Markdown. You can even include HTML in your post if you’d like. The version of Markdown that Jekyll currently uses is Kramdown. To see what Markdown syntax Kramdown supports, you can have a look at Kramdown syntax documentation.
Pages
Aside from posts, you could also create what’s called pages in Jekyll. When you think about a typical website, in the navigation it usually has links for the about and contact page.
There are two methods to create a page in Jekyll.
The first method is to create Markdown or HTML files at the root level of your Jekyll project.
.
├── _includes
├── _layouts
├── _posts
├── _sass
├── _site
├── css
├── _config.yml
├── about.md
├── contact.md
├── feed.xml
└── index.html
This method produces URLs ending with the .html file extension. So the URL for the about page would be http://example.com/about.html.
The second method is to place index.html files within folders.
.
├── _includes
├── _layouts
├── _posts
├── _sass
├── _site
├── css
├── _config.yml
├── about
│ └── index.html
├── contact
│ └── index.html
├── feed.xml
└── index.html
This method produces clean URLs without the .html file extension. So the URL for the about page for this method would be http://example.com/about/.
If you’d like you could also create clean URLs with the first method. You could do this by either setting a permalink key in the Front Matter of a page file:
---
layout: page
title: About
permalink: /about/
---
Or the alternative is to set a key-value pair in your project’s _.config.yml file that all page files will inherit:
# _.config.yml
...
permalink: /:title/
...
Setting a key-value pair in the _.config.yml file is preferable since you can set it once and not have to worry about your permalinks every time you create a new page file.
Once the page file is created, like post files, you’ll have to add some Front Matter. At a minimum, a page file must have a layout and a title key defined. After the Front Matter is defined you can start writing the content for your page after the second set of --- triple-dashes.
---
layout: page
title: About
permalink: /about/
---
I'm a work-from-home father who eats way too much pizza.