How to setup a new Jekyll Blog

In this howto I will explain how you can create and upload your blog to a webserver. I do not want to reinvent the wheel, so I will point you to some existing resources with my notes.

First Andrew Munsell has written an awesome Jekyll tutorial, but it is somewhat dated. Keep in mind that he is using a really old Jekyll and Bootstrap version. To get the most out of it you should download the most recent Jekyll and Bootstrap. gem install jekyll will install the correct version out of the box anyways.

In some cases the output does not look as in the screenshots. Bootstrap has changed considereably over the years, so just adopt the new structure. You can easily look it up in the CSS and component documentation.

For example: I hat to change the pagination from the article to match the current Bootstrap markup:

<nav>
  <ul class="pagination">
    {% if paginator.previous_page %}
      {% if paginator.previous_page == 1 %}
        <li><a href="{{ site.baseurl }}/"><span aria-hidden="true">&laquo;</span><span class="sr-only">Prev</a></li>
      {% else %}
        <li><a href="{{ site.baseurl }}/page{{ paginator.previous_page }}"><span aria-hidden="true">&laquo;</span><span class="sr-only">Prev</a></li>
      {% endif %}
    {% else %}
      <li><span class="disabled"><span aria-hidden="true">&laquo;</span><span class="sr-only">Prev</span></li>
    {% endif %}
    {% if paginator.page == 1 %}
      <li class="active"><a href="#">1 <span class="sr-only">(current)</span></a></li>
    {% else %}
      <li><a href="{{ site.baseurl }}/">1</a></li>
    {% endif %}
    {% for count in (2..paginator.total_pages) %}
      {% if count == paginator.page %}
        <li class="active"><a href="#">{{ count }}</a></li>
      {% else %}
        <li><a href="{{ site.baseurl }}/page{{ count }}">{{ count }}</a></li>
      {% endif %}
    {% endfor %}
    {% if paginator.next_page %}
      <li><a href="{{ site.baseurl }}/page{{ paginator.next_page }}"><span aria-hidden="true">&raquo;</span><span class="sr-only">Next</a></li>
    {% else %}
      <li><span class="disabled"><span aria-hidden="true">&raquo;</span><span class="sr-only">Next</span></li>
    {% endif %}
  </ul>
</nav>

Another important point is that instead of site.url you have to use site.baseurl. It usually stays blank and only holds the absolute path prefix to your site. If you website is http://example.com/my/cool/blog your _config.yml needs to have the following code. baseurl = "/my/cool/blog". In development you can overwrite it with the command: jekyll server --watch --baseurl "/some/other/url".

Other than that the howto is really good.

Once you have setup your blog you need to add some markup to make it search engine friendly.

David Einsinger’s post about Adding Open Graph Tags to Jekyll has all the information you need.

One problem is that the opengraph urls are only absolute to the current server, which is not guaranteed to work. I use the following workaround.

Add a new variable to your _config.yml file.

full_url: "http://martinstoev.de"

Then change the code to look like this:

<meta content="{{ site.title }}" property="og:site_name">
{% if page.title %}
  <meta content="{{ page.title }}" property="og:title">
{% else %}
  <meta content="{{ site.title }}" property="og:title">
{% endif %}
{% if page.title %}
  <meta content="article" property="og:type">
{% else %}
  <meta content="website" property="og:type">
{% endif %}
{% if page.description %}
  <meta content="{{ page.description }}" property="og:description">
{% else %}
  <meta content="{{ site.description }}" property="og:description">
{% endif %}
{% if page.url %}
  <meta content="{{ site.full_url }}{{ page.baseurl }}" property="og:url">
{% endif %}
{% if page.date %}
  <meta content="{{ page.date | date_to_xmlschema }}" property="article:published_time">
  <meta content="{{ site.full_url }}{{ site.baseurl }}/about" property="article:author">
{% endif %}
{% if page.image %}
  <meta content="{{ site.full_url }}{{ site.baseurl }}/assets/images/{{ page.image }}" property="og:image">
{% else %}
  <meta content="{{ site.full_url }}{{ site.baseurl }}/assets/images/avatar-1024x1024.jpg" property="og:image">
{% endif %}
{% if page.categories %}
  {% for category in page.categories limit:1 %}
  <meta content="{{ category }}" property="article:section">
  {% endfor %}
{% endif %}
{% if page.tags %}
  {% for tag in page.tags %}
  <meta content="{{ tag }}" property="article:tag">
  {% endfor %}
{% endif %}

This will break on your development machine, but works fine in production.

Now you are good to go.

In a later post I will describe how to automate publishing your blog with Capistrano.