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:
- Create a folder locally and initialize
git
repository in that folder bygit init
. - Create a simple
index.html
and add it to the repo bygit add index.html
. - Commit you changes by doing
git commit -m 'init'
. - Create a remote repository on Github as described here. Name it
NAME.github.io
, replacingNAME
with desired page name. - If needed setup
ssh
keys as described here. - Add remote repository to your local repository by
git add remote REMOTE_URL
. More detailed steps are can be found here. - Push changes to remote repository with
git push origin master
and you should be able to access your page atNAME.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.
.
Simple steps to get started:
- Clone
Poole
repository locally withgit clone https://github.com/poole/poole.git
- Create another GitHub repository same way as with personal page.
- Remove original remote repository from
Poole
bygit remote remove origin
. - 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 →
<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 →
<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 forPython
provides an interesting system for generatingmarkdown
andhtml
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.