jekyll-scholar – gykovacs's blog on many things

Introduction

A couple of days ago I have realized that my presence on the Internet is very limited. In order to improve my visibility, I decided to build a website where my CV, list of publications and some code for download are available. As an enthusiast of open source and scripting, I was sure that I won’t use the browser-based website builders, like wix.com. Instead, I try to discover the world of open source static generators, which seem to be the handiest for me.

The result can be visited at gykovacs.github.io. In the rest of this post, I describe how to create, customize and deploy a similar website in 6 simple steps.

Choosing the right technology

I found a wide variety of static generators that can be used for building simple but fancy websites by scripting. One can find a great comparison of available technologies here: link.

The features I was looking for:

fancy themes – What I really want is a clean but good looking, eye-candy website;
publications – one of the main purpose of creating the website is to make my work available on the Internet. Consequently, I want a simple way to generate and update the list of publications, preferably based on my already existing BibTex file;
free – I want the technology and the hosting be totally free.

After doing a deep dive into the world of technologies, I decided to try hugo.io, because I really liked the academic theme (https://github.com/gcushen/hugo-academic/), it seemed to be quite popular, simple and available for Windows and Linux, as well. However, it turned out soon that there are no built-in features neither plugins enabling the handling of publications.

Finally, I decided to turn to Jekyll, because the plugin called jekyll-scholar provides a genuine way to handle publications.

Step 1: Install Jekyll

Installing Jekyll is pretty simple in Linux environments as it is part of the repositories of popular distributions. For example, in Ubuntu and its variants:

$ [sudo] apt-get install jekyll

Step 2: Download the dummy code of a likable theme

As Jekyll is pretty popular, there are many websites collecting fancy themes for it, check out them and choose the most likable one:

My personal taste was totally satisfied by the pretty simple Hyde theme, which can be downloaded or cloned from https://github.com/poole/hyde. Create a folder to store your website related stuff and clone the Hyde repository into it. For example

$ mkdir webpage
$ cd webpage
$ git clone https://github.com/poole/hyde.git
$ cd hyde

You can test if it works on your local machine by issuing

$ jekyll serve

in the directory and checking the website served at port 4000 of your localhost by typing http://127.0.0.1:4000// into the browser.

At this point, you have a fancy Jekyll theme working.

Step 3: Customize the content of the pages

The most important file in the downloaded code is _config.yml, this is where the main configurational properties of the page are stored. In the case of the Hyde theme, I kept the default settings for the technical attributes and changed the descriptors title, tagline, description, url, author, and repo. My _config.yml looks like:

# Dependencies
markdown: redcarpet
highlighter: pygments

# Permalinks
permalink: pretty
relative_permalinks: false

# Setup
title: 'Gyorgy Kovacs'
tagline: 'Gyorgy Kovacs'
description: 'PhD in Informatics'
url: https://gykovacs.github.io
baseurl: /

author:
    name: 'Gyorgy Kovacs'
    url: https://gykovacs.github.io

paginate: 5

# Custom vars
version: 2.1.0

github:
repo: https://github.com/gykovacs

Maybe some of the fields like description do not have the right content, but on the sidebar of the theme, the right thing got to the right position.

Customize the website according to your personal taste. Feel free to open the existing pages and rewrite/customize their content. You can add any further page in the root of the directory with the extensions .html or .md and the page will be automatedly included in the menu of the sidebar. Both the .html and .md files can contain HTML or Markdown language code. The latter one gives a really easy way to develop the content. The only thing you should be careful that all .md Markdown pages should begin by specifying the layout and the title of the page, like

---
layout: page
title: Professional experience
---

A side remark on blogging

One of the main features of Jekyll is blogging. You can write posts in Markdown, copy them into the right folder and the blog post appears. What is more fascinating is that GitHub supports Jekyll, so, you can host your website in a GitHub repository and all you have to do to write a blog post is to update your repository, GitHub executes Jekyll and the post appears. On the contrary of these fancy features, for some reasons I decided to move my blogging activity to one of the web-based services:

On the one hand, Jekyll is not available for Windows (yes, I use Windows sometimes). This is the less important issue, as you have git on Windows/Linux/Mac, so you can still update your repository in the same way from any environments.
The other, more important point is that GitHub does not support the use of Jekyll plugins like jekyll-scholar, thus generating the website on GitHub would divest from the most important feature: the automated generation and updating of the publication list. You can still generate your website locally and host only the generated pages on GitHub, however, as I mentioned earlier, it wouldn’t work on Windows.

Taking into account all of these, I decided to do the blogging on WordPress.com, and link that blog to the one automatically generated by Jekyll. In order to achieve this, I had to change the sidebar.html file in the _includes directory:

<div class="sidebar">
<div class="container sidebar-sticky">
<div class="sidebar-about">
<h1>{{ site.title }}</h1>
{{ site.description }}</div>
<nav class="sidebar-nav">
			{% comment %}
				The code below dynamically generates a sidebar nav of pages with `layout: page` in the front-matter. See readme for usage.
			{% endcomment %}{% assign pages_list = site.pages %}
			{% for node in pages_list %}
				{% if node.title != null %}
					{% if node.layout == "page" %}
						<a class="sidebar-nav-item{% if page.url == node.url %} active{% endif %}" href="{{ node.url }}">{{ node.title }}</a>
					{% endif %}
				{% endif %}
			{% endfor %}
			<a class="sidebar-nav-item" href="https://drive.google.com/open?id=0B3E8L0dtBKcsWUNXalNQYTJuc3c">Download detailed CV in PDF</a>
			<a class="sidebar-nav-item" href="gykovacsblog.wordpress.com">Blog</a>
			<span class="sidebar-nav-item">Jekyll Hyde, Currently v{{ site.version }}</span>
</nav>

© {{ site.time | date: '%Y' }}. All rights reserved.</div>
</div>

Step 4: Generating a fancy publication list

In order to get a fancy publication list from your BibTex file, you need to get jekyll-scholar, so go to https://github.com/inukshuk/jekyll-scholar and clone it using git, or alternatively download it as a package. Before cloning the repository, don’t forget to change your working directory to from hyde to its parent we called webpage. Then call

$ git clone https://github.com/inukshuk/jekyll-scholar.git

Navigate into the cloned directory and fire:

$ cd jekyll-scholar
$ [sudo] gem install jekyll-scholar

First I got some build errors as I didn’t have the ruby sources installed on my Ubuntu, this can be resolved by

$ [sudo] apt-get install ruby-dev

Go back to the directory of the dummy website (in our case hyde), and create a new directory called _plugins. In order to get jekyll-scholar work, create a file in the _plugins directory called ext.rb with the following content.

$ mkdir _plugins
$ echo "require 'jekyll/scholar'" >> _plugins/ext.rb

You also need to update the _config.yml file to set some basic properties of jekyll-scholar. I have added the following lines

scholar:
    style: apa
    bibliography: refs.bib
    replace_strings: true
    query: "@*"

which reads as:

the style of publications is “apa”, which is one of the most basic styles available in BibTex,
the bibliography is available in a file called refs.bib,
queries can be made by the special character sequence “@*”.

Create another directory called _bibliography and copy your .bib BibTex file there. My BibTex entries have some custom fields and look like:

@article{j006,
    author="Gy. Kov\'acs and A. Hajdu",
    title="A Self-Calibrating Approach for the Segmentation of Retinal Vessels by Template Matching and Contour Reconstruction",
    journal="Medical Image Analysis",
    volume="29(4)",
    pages="24--46",
    year="2016",
    note="(IF=4.565)",
    doi={10.1016/j.media.2015.12.003},
    group="journal",
    preprint = {https://drive.google.com/open?id=0B3E8L0dtBKcsUUtSRWloVFpCRlE},
    link = {http://www.medicalimageanalysisjournal.com/article/S1361-8415(15)00184-X/fulltext?cc=y=},
    code = {http://gykovacs.github.io}
}

The custom fields are

group, which makes the querying of publications easier,
preprint, which is a link to the preprint version of the document at my Google Drive,
link, containing a link to the publisher’s website and
code, containing a link to corresponding codes on the web.

Finally, create a new Markdown file in the root of your website, called publications.md with a content like

---
layout: page
title: List of publications
---

## Journal Papers

{% bibliography --query @*[group=journal] %}

The page will automatically be included in the menu of the website on the name “List of publications” and will contain all the entries having group = "journal" in the BibTex file. Use simply

{% bibliography %}

to print the entire bibliography. Now, building the page or simply calling

$ jekyll serve

in the root of the website will add a new page called “List of publications” to the sidebar with the references generated from the .bib BibTex file.

Step 5: Customize the bibliography

A simple list of publications is cool. However, I have found some really fancy solutions using Jekyll and jekyll-scholar, and I tried to create my own variant of that. My customization was highly influenced by the great works of:

In order to customize the look of the bibliography, you need to create a template file which describes how to visualize the entries of your publication list. To be exact, the file describes what to visualize after the line is rendered according to the BibTex style specified in the _config.yml (in our case “apa”). Let us call this template file bibtemplate.html and create it in the _layouts directory of your website’s root. In my case the content of the file is:

---
---
<div class="text-justify">{{reference}}</div>
<button class="button0"  onclick="toggleBibtex{{entry.key}}()">Bibtex</button>

{% if entry.doi %}
	<a href="{{ entry.doi | prepend: 'http://doi.org/' }}"><input class="button1" type="button" value="doi" /></a>
{% endif %}

{% if entry.preprint %}
	<a href="{{ entry.preprint }}"><input class="button2" type="button" value="preprint" /></a>
{% endif %}

{% if entry.link %}
	<a href="{{ entry.link }}"><input class="button4" type="button" value="link" /></a>
{% endif %}

{% if entry.code %}
	<a href="{{ entry.code }}"><input class="button3" type="button" value="code" /></a>
{% endif %}
<div id="a{{entry.key}}" style="display: none;">
<pre>{{entry.bibtex}}</pre>
</div>
<script>
function toggleBibtex{{entry.key}}(parameter) {
    var x= document.getElementById('a{{entry.key}}');
    if (x.style.display === 'none') {
        x.style.display = 'block';
    } else {
        x.style.display = 'none';
    }
}
</script>

This can be interpreted as follows:

I have implemented a hidable paragraph for the entire BibTex entry, as it is pretty useful to have these entries available if someone wants to cite your work properly. The hidden paragraph is implemented in the second div environment of the code, the id of the div comes from the key of the BibTex entry to make it referrable and the content of the div is the BibTex entry itself as a preformatted text. By default the div is hidden by setting the style attribute "display:none". The JavaScript code in the script environment is a function which changes the hidden status of the entry to visible. The name of the function contains the key of the BibTex entry to make it well-defined. The first visible object after the rendered BibTex entry will be a CSS button created in the button environment, stilized by the class button0 and the onclick-handler function is added, as well.
The rest of the file contains the code of the other objects, which is pretty similar: if any of the preprint, doi, link or code custom fields of the BibTex entry is populated, the corresponding link is rendered.

In order to make this template work, two more things are left to do. On the one hand, one has to specify in the _config.yml file that a bibliography_template has been implemented. This can be done by adding a further line with the name of the file:

scholar:
    style: apa
    bibliography: refs.bib
    bibliography_template: bibtemplate
    replace_strings: true
    query: "@*"

The last thing to do is to specify the look of the objects we defined in the file bibtemplate.html by adding the proper CSS entries to one of the .css files in the public/css directory. I have added entries to syntax.css like

.button0 {
    background-color: #4CAF50;
    border: none;
    color: white;
    padding: 4px 8px;
    text-align: center;
    text-decoration: none;
    display: inline-block;
    font-size: 10px;
    font-weight: bold;
    margin: 2px 1px;
    cursor: pointer;
    border-radius: 5px;
}

for the button0, button1, button2, button3 and button4 styles, differing in the background-color attribute only. Once you are ready with all of these, you can check your fancy publication list by issuing

$ jekyll serve

in the root of your website source and checking the result in your browser.

One more thing to customize is the structure of the entries in the list of publications. Initially, we used the “apa” style (specified in the _config.yml file), which refers to the style of the journal of the American Psychological Association. This is a widely used style, however, one may want to customize it to some extent. For example, this style does not add the content of the note field of bibentries to the list of publications.

Generally, one has two options: on the one hand, one can discover the hundreds of styles available at http://editor.citationstyles.org/about/. Download the .csl definition of the style, copy it into, say, the _layout directory and modify the _config.yml file by changing the string “apa” to the name of the file downloaded. The other option is to create your own style, or modify one of the existing files according to your taste. The citation styles page has a very handy editor to modify existing or create new citation styles.

Step 6: Deploy the website on GitHub

Jekyll generates the real website into the directory _site. You can copy the contents of this directory to any webhosting service and your website becomes visible. I decided to use GitHub to host my website. However, as mentioned before, the jekyll-scholar plugin does not work on GitHub, so you can’t simply upload the entire code and wait for GitHub to build your page, because it won’t work. The only workaround is to deploy the generated website to GitHub. First, create a directory with the username of your GitHub account and the .github.io postfix:

$ mkdir username.github.io

Navigate to the directory and initialize a new git repository by

$ cd username.github.io
$ git init

Now move the contents of the generated _site Jekyll directory to this new git repository:

$ cp -R ../hyde/_site/* .

Then, add everything to the repository, commit and push the files to your GitHub repository:

$ git add --all
$ git commit -m "First version"
$ git push

If everything worked fine, your website will be available on the URL http://username.github.io in a couple of minutes.

+1: Setting up Google Analytics

Google Analytics is a great tool to track the popularity of your website. In order to set up Google Analytics working, one has to register an account and register the URL of your website. Then, Google Analytics provides a JavaScript snippet (in red frame) that has to be embedded into all your websites properly. This snippet contains your unique tracking code.

analytics

In order to add this code snippet to all your pages, create a new file called analytics.html in your _layouts directory, and put the script into it. Then, add the following lines just before the closing body tag of your default.html file in the _layouts directory:

{% if jekyll.environment == 'production' %}
{% include analytics.html %}
{% endif %}

These lines ensure that the analytics code will be included only in production environment. If you use GitHub to generate your website, it will set the JEKYLL_ENV environment variable properly and the analytics code will be embedded. If you copy only the generated website to GitHub, make sure that you run the jekyll build or jekyll serve commands with the JEKYLL_ENV set to production. For example:

$ JEKYLL_ENV=production jekyll build

You can check the embedding by loading your website and inspecting the source code in a browser. It should contain the analytics script right before the closing body tag. If the script is present in the source of the website, you can start monitoring the user activity by looking at the wide variety of statistics available at Google Analytics.

Summary

If you have any remarks regarding the previous tutorial, just leave a comment or contact me at gyuriofkovacs@gmail.com.

The source code of my entire website is available for download at https://github.com/gykovacs/gykovacs.website

Tag: jekyll-scholar

Building a simple and flexible academic-like website in 6 easy steps