How to build a blog using Github, Jekyll and Lanyon

UPDATE: I redesigned this blog using Centrarium. Though my blog does not reflect the steps in this post, this tutorial helped me to rebuild my blog. I hope this helps you too!

I built this blog using Github pages, Jekyll and the Lanyon theme. The most amazing part is that it’s free, minimalist, uses Markdown and you can get it running in no time! Also, it does not feel bloated like Wordpress, etc.

Here’s a short tutorial on how I made this blog. Ready to learn? Let’s get started!

Note: If you are not interested to do the setup yourself, simply fork my repo and make the changes to include your details.

1. Installing Jekyll

We are going to use Jekyll as a static site generator to build our website. Jekyll is written in Ruby and requires Ruby to be installed on your system. Chances are, you already have ruby installed. But Jekyll 2 requires v1.9.3 or greater and Jekyll 3 requires v2.0 or greater. Here, we’ll use v2.0. Note that we’ll also need the development headers. So go ahead and type this in your terminal:

$ sudo apt-get install ruby2.0 ruby2.0-dev

Now, check your ruby version using:

$ ruby --version

When I type that into my terminal, I get something like this: ruby 2.0.0p384 (2014-01-12) [x86_64-linux-gnu]. If you find some other ruby version as your default version, you’ll need to set this as your default one. For this, you can use RVM.

$ sudo apt-get install zlib1g-dev build-essential libssl-dev libreadline-dev libyaml-dev libsqlite3-dev sqlite3 libxml2 libxml2-dev libxslt-dev gawk libgdbm-dev libncurses5-dev automake libtool bison libffi-dev nodejs
\curl -sSL https://get.rvm.io | bash -s stable

Then set the default ruby version using (you can use other ruby versions as well):

$ rvm --default use 2.0.0

You’ll also need Rubygems - which is a package management framework for Ruby. You can download it from here. Now, we can finally install jekyll!

$ gem install jekyll

Great, now we can proceed to use Lanyon! :)

2. Using Lanyon

I like the Lanyon theme since it focuses more on content and is minimalistic. If you are not a fan of sidebars, you can checkout Poole or if you prefer a static sidebar, have a look at Hyde. Decided on your theme? Let’s move ahead!

First of all, you will need to create a repository having the name username.github.io. For example, my Github username is nikhita so I have named by repo as nikhita.github.io. After you do this, clone this repository onto your local computer. Replace username with your real username.

$ git clone https://github.com/username/username.github.io.git

Next, download the Lanyon zip file from here and extract it into your username.github.io folder. Alternatively, you can fork the Lanyon repo and change the forked repository’s name as username.github.io. After that, clone the forked repo onto your local computer.

Now, let’s move into our folder and run the default page on our local server.

$ cd username.github.io
$ jekyll build
$ jekyll serve

Open up your browser and go to: http://localhost:4000 and voila, the website is hosted locally on your system and is ready to be tweaked!

3. Exploring the directory structure

Before we go ahead and make customizations, let’s have a look at the files in your folder. Once we learn the design, we can go ahead and make changes confidently!

.
|-- 404.html
|-- about.md
|-- atom.xml
|-- _config.yml
|-- _includes
|   |-- head.html
|   `-- sidebar.html
|-- index.html
|-- _layouts
|   |-- default.ht_ml
|   |-- page.html
|   `-- post.html
|-- LICENSE.md
|-- _posts
|   |-- 2013-12-31-whats-jekyll.md
|   |-- 2014-01-01-example-content.md
|   `-- 2014-01-02-introducing-lanyon.md
|-- public
|   |-- apple-touch-icon-precomposed.png
|   |-- css
|   |   |-- lanyon.css
|   |   |-- poole.css
|   |   `-- syntax.css
|   `-- favicon.ico
`-- README.md

Here is a brief explanation of what you see:

When you run Jekyll, it creates a folder called _site with the static website inside it. Every file or folder in the repo will get copied into the _site folder unless it begins with an underscore.
_config.yml is the configuration file, which is the first file we are going to change.
index.html is your front page and about.md is a static page. You can add other static pages by creating markdown files (which we will be doing further). 404.html is pretty self-explanatory.
atom.xml is for the RSS reader.
_includes and _layouts folders contain the boilerplate HTML required to build the site.
_posts include the posts that you’ll be…well…posting. They are Markdown files.
public contains favicon information and CSS files.

Still with me? Let’s do some tweaking! :)

4. Modifying configuration file

The first thing you want to do is change the _config.yml file. Open it in your favorite text editor and edit the sections in Setup and About/contact according to your preferences.

You can add other details as well. Have a look at my _config.yml for reference.

Lanyon is built on Poole and Poole does not support Jekyll 3 yet. You can check this issue. For this, you’ll need to add:

gems: [jekyll-paginate]
paginate_path: "page:num"

and comment out: relative_permalinks: true.

Now we are good to go!

5. Adding an archive page

Lanyon, by default, does not provide an archive page. So let’s make one. In your root folder, create an archive.md file and add the following contents to it.

---
layout: page
title: Archive
---


{% for post in site.posts %}
  * {{ post.date | date_to_string }} &raquo; [ {{ post.title }} ]({{ post.url }})
{% endfor %}

Now run the following commands again and go to http://localhost:4000 to see the Archive page on your website. Note that we’ll be making lots of changes so it’s a good idea to keep checking what changes you are making. So keep these commands in mind!

$ jekyll build
$ jekyll serve

6. Integrating Disqus comments

Obviously you’ll need a Disqus account for this. Head to the website, create an account and it’ll ask you if you want to “Add Disqus to your site”. If you already have an account, click on the gear icon on the top right corner and select the option. Follow the steps until it gives you a shortname for your website.

Now open the _layouts/default.html file and add the line as shown:

<div class="container content">
  
  {{ content }}
  {% include comments.html %}
  
</div>

The parent divs are wider than the content container so adding the include statement outside of this one will make the comments section stretch across the entire page, rather than being confined to the content’s area.

Now that you have included comments.html, let’s create it! Create a file called comments.html in the _includes folder and add the following lines. Make sure that you replace your-shortname-here with your actual shortname.

{% if page.comments %}
<div id="disqus_thread"></div>
<script type="text/javascript">
    /* * * CONFIGURATION VARIABLES * * */
    var disqus_shortname = 'your-shortname-here';
    /* change the above line to include your real shortname */
    var disqus_identifier = "{{ site.disqusid }}{{ page.url | replace:'index.html','' }}";
    
    /* * * DON'T EDIT BELOW THIS LINE * * */
    (function() {
        var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
        dsq.src = '//' + disqus_shortname + '.disqus.com/embed.js';
        (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
    })();
</script>
<noscript>Please enable JavaScript to view the <a href="https://disqus.com/?ref_noscript" rel="nofollow">comments powered by Disqus.</a></noscript>
{% endif %}

Note that the comments will not run if you don’t set comments to true in the YAML frontmatter of the posts. So open any post (say, 2014-01-02-introducing-lanyon.md) from the _posts folder and add the following line on top:

---
layout: post
title: Introducing Lanyon
comments: true /*add this line*/
---

Now run jekyll build and jekyll serve again to see Disqus comments enabled on the post! :)

7. Enabling Google Analytics

Again, you’ll need a GA account for this. In the Admin tab, you’ll find Tracking info under the Property section. Under that you’ll find a tracking code with a script. Something like this:

<script>
  (function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
  (i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
  m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
  })(window,document,'script','https://www.google-analytics.com/analytics.js','ga');

  ga('create', 'UA-82647777-1', 'auto');
  ga('send', 'pageview');

</script>

Create a file called google_analytics.html in the _includes folder and add the the code GA gave you. Do not paste the code I posted above - you’ll mess up my stats! :(

Now add the following line in default.html inside the _layouts folder.

  <body>
    {% include google_analytics.html %} /*add this line*/
    {% include sidebar.html %}

Save it and you are good to go!

8. Adding a custom favicon

You can create a favicon using GIMP or you can use an easy online option. I rolled the online way.

If you plan to use the online method, extract the files to the public folder (which should have a placeholder favicon.ico).

Go to head.html in _includes and add the following line:

<!-- Icons -->
<link rel="icon" sizes="16x16 32x32 64x64" href="/public/favicon.ico">

Note: If you used the link that I provided, you’ll have many other images. Have a look at the readme file provided after extraction and change the href link to include {{ site.baseurl }}/public/. Look at my head.html to understand it better.

Cool, now we have got our custom favicon in action!

We’ll use Gravatar for this. Go to the website, create an account and upload your image. According to the instructions here, you’ll need the md5 hash. For this, you’ll need to type a php command. Go here and run:

echo md5(strtolower(trim("MyEmailAddress@example.com")));

You’ll get a md5 hash. Copy the hash and add it in your _config.yml file as shown:

#About/contact

gravatar_md5: your-md5-hash-here

Then open your sidebar.html file and add this line:

<div class="sidebar" id="sidebar">

/*add the following lines*/
 <div class="sidebar-logo" style="align:center">
      <img src="http://www.gravatar.com/avatar/?s=120" />
  </div>

To make your photo look good on the sidebar, create a custom.css file in public/css and add the following lines:

.sidebar-logo {
      padding: 1.5rem;
}
  
.sidebar-logo img {
      border-radius: 50%;
      -moz-border-radius: 50%;
      -webkit-border-radius: 50%;
      width: 160px;
      margin: 0 auto;
}

Save it, run your server and look at your pretty picture on the sidebar! :)

I have used icons from the Font Awesome library. If you don’t like the icons I used, you can choose other icons of your own - after all, it’s your website!

Add the following line with other CSS links in _includes/head.html:

<link rel="stylesheet" href="//maxcdn.bootstrapcdn.com/font-awesome/4.3.0/css/font-awesome.min.css">

In your sidebar.html setup a div container for all these icons to go in:

<div id="contact-list" style="text-align:center">
<!-- contact icons go here --> 
</div>

You can link multiple social media accounts in the div. For example, if you want to link your LinkedIn account, add the following lines:

For email, href="mailto: " and for rss, href="{{ site.url }}/atom.xml".

Awesome, our social media buttons are ready for action!

11. Changing the font

Personally, I didn’t like the default Lanyon font. Head over to Google Fonts and choose a font that you love. Google will provide you with a stylesheet link. Something like this:

<link href="https://fonts.googleapis.com/css?family=Average" rel="stylesheet"> 

Add this line to head.html in the list of CSS links. Now, go to public/css/lanyon.css and your font to the font-family.

/* I added the Average font here */
html {
  font-family: "Average", "PT Serif", Georgia, "Times New Roman", serif;
}

Finally, you have even changed your fonts! Yay!

12. Other tips

Some hacks to make your blogging experience better:

Set up a _drafts folder in your root directory. Save the posts without the date, eg: title-without-date.md. In order to preview this, run

$ jekyll serve --drafts

For adding images to your site, you can setup an images folder and use the images with <img src="{{ site.baseurl }}/images/file-name-here">.

13. Conclusion

References

Hope this blog post helps you! :)

How to build a blog using Github, Jekyll and Lanyon

Table of Contents:

1. Installing Jekyll

2. Using Lanyon

3. Exploring the directory structure

4. Modifying configuration file

5. Adding an archive page

6. Integrating Disqus comments

7. Enabling Google Analytics

8. Adding a custom favicon

9. Adding your photo to the sidebar

11. Changing the font

12. Other tips

13. Conclusion

References

Table of Contents:

1. Installing Jekyll

2. Using Lanyon

3. Exploring the directory structure

4. Modifying configuration file

5. Adding an archive page

6. Integrating Disqus comments

7. Enabling Google Analytics

8. Adding a custom favicon

9. Adding your photo to the sidebar

10. Adding social media buttons

11. Changing the font

12. Other tips

13. Conclusion

References