Roman Tsegelskyi's blog    About    Atom    RSS

Personal page and blog using Github pages and Jekyll

Having a personal web page and blog can be very beneficial for a developer. I recently decided to create ones myself and ironically enough my first post will is a guide/report with the problem I faced and how I solved them would be useful. This port is meant to help people that are familiar with what Git and GitHub is to get up and running with GitHub Pages and Jekyll in just a couple of hours.

Creating a personal page using GitHub pages

GitHub Pages are public web pages hosted for free through GitHub. Github Users are allowed to have one personal page and unlimited amount of pages for different projects.

Since there are many articles about creating GitHub Pages, I will only go through high-level steps for creating a personal page:

  1. Create a folder locally and initialize git repository in that folder by git init.
  2. Create a simple index.html and add it to the repo by git add index.html.
  3. Commit you changes by doing git commit -m 'init'.
  4. Create a remote repository on Github as described here. Name it NAME.github.io, replacing NAME with desired page name.
  5. If needed setup ssh keys as described here.
  6. Add remote repository to your local repository by git add remote REMOTE_URL. More detailed steps are can be found here.
  7. Push changes to remote repository with git push origin master and you should be able to access your page at NAME.github.io.

Templates for the website

Creating a basic website might be quick and easy, but who needs a site with just a couple of words? Assuming you don't know HTML that well (like me), or don't want to spend a lot of time creating a pretty website a good option is to use one of countless templates and customize it for yourself.

Here are some good websites to get started with:

Google Analytics

In case you love statistics or just curious if anyone visit you website, adding something to track visitor seems like a good idea. My choice was Google Analytics since it's relative simple and works great. To add analytics support go to Admin tab and create new account. After you enter all the needed information and accept the agreements, you will get tracking code, something like this:

  (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','//www.google-analytics.com/analytics.js','ga');

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

Insert this code anywhere at your index.html page and data will get automatically uploaded to analytics.

Setting up a blog

Recently I learned about Jekyll - static websites generator and for me it seemed like a great and simpler alternative to dynamic platform like Wordpress, Joomla, etc. Besides its simplicity, it makes backups so much easier and avoids most common security concerns caused by running dynamic websites. Jekyll allows to write posts in Markdown which is another big plus. Moreover, code examples are very nicely embedded in the website. So combining with a fact that GitHub provides free hosting for Jekyll blogs, I was completely sold for it.

Poole

Even though setting up Jekyll is relatively easy, there exists a really nice bundle repository - Poole to simplify the process even more. Poole calls itself "the butler for Jekyll" and it indeed reduces the time needed to setup Jekyll powered blog to the matter of minutes. Of course the default design is no unique, but it allows to have a very quick start.

demo.png.

Simple steps to get started:

  1. Clone Poole repository locally with git clone https://github.com/poole/poole.git
  2. Create another GitHub repository same way as with personal page.
  3. Remove original remote repository from Poole by git remote remove origin.
  4. Add your remote Github repository created at step 2 using git add remote REMOTE_URL.

Note that even if you push changes to the remote repository, you will probably not be able to access blog yet, since _config.yml is not correct which we will address in a bit, but you can test it locally as described in next subsection.

Running Jekyll locally

To test locally the correctness of the setup, you will need to install Jekyll using RubyGems:

gem install jekyll

And to run Jekyll locally:

jekyll serve

This is basically all you need. Of course, Jekyll provides a variety of options, a good intro to which might be found here.

Integrating blog as a part of personal page

After you clone the poole repository, it's time to link it to your page. For that just edit _config.yml:

# Setup
title:               Your Blog Titme
tagline:             ''
description:         ''
home:                http://NAME.github.io
url:                 http://NAME.github.io/blog_name
baseurl:             /BLOG_NAME/
paginate:            5
paginate_path:       "/page:num/"
exclude:             ['posts']

Push the changes to your repository and you will be able to see the blog under NAME.github.io/BLOG_NAME

Comments

One of the main things that I was concerned about when creating static blog is having comments functionality. But Disquis seems to solve that problem very well. Create a file _includes/comments.html which includes the code provided by Disqus after registration. After that add modify the file _layouts/default.html to include the line:

<div id="disqus_thread"></div>
<script type="text/javascript">
    /* * * CONFIGURATION VARIABLES * * */
    var disqus_shortname = 'programminginvestigations';

    /* * * 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>
<a href="http://disqus.com" class="dsq-brlink">comments powered by <span class="logo-disqus">Disqus</span></a>

Setting the comments this way allows easy enabling/disabling of comments on a page-by-page basis. All you need have to do is set comments: True in the YAML header of the post.

Analytics

Adding Google Analytics to the blog is similar to adding comments. First, create an account through Google Analytics Admin section as you did for peronal page. Google will give you the javascript tracking code to embed on every website, which you should put in _includes/google_analytics.html. Finally, to enable analytics on all of the pages of the blog add the include to _layouts/default.html:

<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','//www.google-analytics.com/analytics.js','ga');

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

</script>

Social Buttons

There are different options for ways to adding sharing buttons to your blog (for example this and this), but after some searching, I went for simplicity described in this article on CodingTips blog. I would encourage reading an original article, but I also wanted to provide simplified steps.

As in other steps, create _includes/share.html with following contents:

<div class="share-page">
    Share this on &rarr;
    <a href="https://twitter.com/intent/tweet?text=Personal page and blog using Github pages and Jekyll&url=http://romantsegelskyi.github.io/2015/07/26/personal-page-blog/&via=&related=" rel="nofollow" target="_blank" title="Share on Twitter">Twitter</a>
    <a href="https://facebook.com/sharer.php?u=http://romantsegelskyi.github.io/2015/07/26/personal-page-blog/" rel="nofollow" target="_blank" title="Share on Facebook">Facebook</a>
    <a href="https://plus.google.com/share?url=http://romantsegelskyi.github.io/2015/07/26/personal-page-blog/" rel="nofollow" target="_blank" title="Share on Google+">Google+</a>
</div>

Next add this to css/_share.scss:

.share-page {
    text-align: center;
    background: $secondary-color;
    color: $light-color;
    padding: 8px 15px;
    border-radius: 5px;
    margin: 1.5 * $spacing-unit 0;

    a {
        font-weight: 700;
        color: #fff;
        margin-left: 10px;

        &:hover {
            border-bottom: 1px dashed #fff;
        }
    }
}

And and import in styles.scss:

@import "share";

Finally, to enable sharing on all of the pages of the blog add the include to _layouts/default.html:

<div class="share-page">
    Share this on &rarr; 
    <a href="https://twitter.com/intent/tweet?text=Personal page and blog using Github pages and Jekyll&url=http://romantsegelskyi.github.io/2015/07/26/personal-page-blog/&via=&related=" rel="nofollow" target="_blank" title="Share on Twitter">Twitter</a>
    <a href="https://facebook.com/sharer.php?u=http://romantsegelskyi.github.io/2015/07/26/personal-page-blog/" rel="nofollow" target="_blank" title="Share on Facebook">Facebook</a>
    <a href="https://plus.google.com/share?url=http://romantsegelskyi.github.io/2015/07/26/personal-page-blog/" rel="nofollow" target="_blank" title="Share on Google+">Google+</a>
</div>

Also keep in mind that same as for comments, sharing can be turned off by setting social: False in the YAML header of the post.

Pages in the header

To add permanent pages (like About, Feeds, CV, etc.) in the blog header you need to specify that in _config.yml. For example the following snippet adds About, Atom and RSS pages, which are in the root of the repository:

pages_list:       
  About: '/blog_name/about'
  Atom: '/blog_name/atom.xml'
  RSS: '/blog_name/rss.xml'

Note that those files can themselves contain Jekyll liquid variable. Nice into to liquid variables can be found here.

Atom and RSS feeds

Poole provides a template for Atom feed by default. It's basic, but serves as a decent starting point. For RSS, there exists a great repository with different templates for RSS feeds. Be sure to check the correctness of the links generated, because all the templates don't contain a reference to blog_name. My RSS and Atom files respectively.

Code Highlighting

Strangely, by default Poole is not setup to support widely accepted triple backticks for code highlighting. Which leaves 2 options:

1) Change to different markdown style in _config.yml to support triple backticks:

markdown:           redcarpet
redcarpet:
      extensions: ["no_intra_emphasis", "fenced_code_blocks", "autolink", "strikethrough", "superscript", "with_toc_data"]

2) Use highlight liquid variable:

{\% highlight python \%}
def yourfunction():
     print "Hello World!"
{\% endhighlight \%}

Which results in 

def yourfunction():
     print "Hello World!"

I personally like the first option more, since I am more used to it, but after all both seem to yield identical results, so it's rather a matter of preferences.

Interesting deployment systems

While setting up personal page and a blog already give a boost in productivity, there are deployment systems that make the process even more efficient:

  • R + knitr. R is a great language primarily used by statisticians and one of it's amazing features is a great support for generating reports using knitr. It the linked blog post the author describes blogging using R stack which might be very useful for data analysis related posts.

  • Python + Pweave. Similar to R + knitr, Pweave for Python provides an interesting system for generating markdown and html while embadding code.

Basic SEO

To improve search engine recognition of the blog, it's good idea to creat sitemap.xml. You can either create one by hand or use the one automatically generated by GitHub. Mine can be viewed here.

comments powered by Disqus