The URL of your website is sometimes overlooked, but it is worth spending a little time to set it right when you start a blog.

What Does It Look Like?

Let’s take a look at the default setting from Jekyll.

Note: the default setting by Jekyll is

# Outputting
permalink:     date

The actual URL for a post with categories looks like this: /jekyll/update/2016/05/18/welcome-to-jekyll.html Let me interpret it, /category/sub-category/year/month/day/file-name.extension. This matches the [Jekyll official document] as /:categories/:year/:month/:day/:title.html.

There are debates over what SEO friendly URLs are. Should or shouldn’t include the category? Should the URL be as short as possible? Should it be stuffed with keywords or not?

So there is no single rule to follow, but there are some suggestions. First, be focused. That is to say, although the length of the URL does not really matter, you should try to keep the URL focus to the theme of your page. Including the date is not necessary and will not help your SEO. Only include them when they make sense. For instance, if your website is a news site and post regularly, and the time is a relevant aspect to the reader (since it’s news), then you should have dates in your URL. The same rule applies to Categories. It will not help your SEO ranking, maybe it is even harmful because it will dilute the ranking power of any other word in your URL. Unless you need the categories to help you, you should omit it.

One more thing, we should omit some words from our URL, not simply use the page/post title. Words that are often left out are: and, but, or, if, that, this, these, the, a, an, in, etc.

Here is an article from MOZ that talks about SEO suggestions if you are interested.

So after all, I decided to contain only the title slug in my URL.

OK. Set It Up

We can set our own rules for the permalink: in _config.yml.

In the document, there are 4 built in styles by Jekyll.

  • date: the default option, /:categories/:year/:month/:day/:title.html
  • pretty : /:categories/:year/:y_day/:title.html
  • ordinal : /:categories/:title.html
  • none : /:categories/:title.html

There is also a list of variables we can use to construct our own permalink schema.

year, month, i_month: Month without leading zeros
day, i_day, short_year, hour, minute, second
title: from the document's filename.
slug: slugified from the document's filename
categories: The specified categories for this Post. If a post has multiple categories, Jekyll will create a hierarchy 

So the setting I chose is very simple. permalink: /:slug

Additional Care

However, using title slug as permalink may lead to some troubles.

What if I have 2 articles that happen to have the same title? When you have tons of posts, this is possible. Thankfully, Jekyll provided a way to detect this kind of errors.

# use jekyll doctor to check duplicate title issue
$ bundle exec jekyll doctor                          
Configuration file: /Users/windd/Documents/develop/@github-blog/blog/_config.yml
# No problem
  Your test results are in. Everything looks fine.

# Oops
Conflict: The URL '/_site/monthly-project-update/index.html' is the destination for the following pages: _posts/2015-03-06-monthly-project-update.markdown, _posts/2015-04-07-monthly-project-update.markdown


Permalinks should be focused. So leave out the dates and categories and any unnecessary parts, but at same time, remember to make it more human-readable for your audience.

Customization To-do list:

  • Permalink: should I contain dates in the URL?
  • Fix fenced code block nested in un/ordered lists
  • Fix the Checkbox
  • Add images with captions to my post
  • Add comments functionality
  • Change a Theme
  • Adding a Navigation
  • Change the code highlighting theme
  • Custom 404 page
  • Create _pages folder for all your pages
  • Add tags to post
  • Change the About page
  • Multilingual?
  • Add search functionality