Welcome! This is the first blog of the site built with GitHub Pages and Jekyll.

In this article, I’d like to introduce the way I set up the site by adding a few features based on the TeXt theme. In particular, some of the add-on design and features are borrowed from al-folio, which is another great Jekyll theme for academics. The reason for choosing TeXt instead of al-folio to build on the site is the diversity of the styles and extensions (i.e., support for audio) provided.

All the source code of the site is available on the source branch of my repo.

Features

Customized Home Page

The default layout of the home or index page of the theme is the list of blog posts (as the layout under the current Blogs section). The layout of the home page is changed by modifying _layouts/home.html.

Personally, I’d like to display a short bio and a few updates (news) about my experience on the home page instead of a list of blogs. I replace the home layout to include a short bio and a list of news as two separate html files, _includes/bio.html and _includes/news.html, respectively. In particular, the html for the new listing, _includes/news-list.html is similar to what we have in _includes/article-list.html. We can add whatever content we want on the home page with similar approaches. In addition, I made a separate copy of the original home layout file to be the layout for the blog listing, _layout/blog_home.html.

With such a setup, we now have a customized index page and a separate blog listing page.

Additional Social Options

TeXt supports several contact options for social platforms including email, Facebook and LinkedIn. whose button appears on the footer of the page by default. We can incorporate additional options by editing the _includes/author-links.html.

To include Google Scholar, we will need to use the icons from Academicons. First, download the latest icon packages and put academicons.css under assets/css/ and the rest under assets/fonts/. Then, add the following line to assets/css/main.scss

@import "academicons.css";

Add the following lines to _includes/author-links.html under the <ul>...</ul> block

{-% if _author.scholar -%}
  <li title="">
    <a class="button button--circle scholar-button" itemprop="sameAs" href="" target="_blank">
    <i class="ai ai-google-scholar"></i>
    </a>
  </li>
{-% endif -%}

Finally, add the scholar option under author in _config.yml.

Bibliography

Unfortunately, TeXt does not come with automatic bibliography support. To enable such support, we incorporate Jekyll Scholar into the site.Jekyll Scholar is a Jekyll extension that converts bibtex to bibliography formatted according to the settings.

To use Jekyll Scholar, we first add the following into the Gemfile:

gem 'jekyll-scholar', group: :jekyll_plugins

Then, add the following into _config.yml

scholar:

  last_name: YOUR_LAST_NAME
  first_name: YOUR_FIRST_NAME

  style: apa
  locale: en

  sort_by: year
  order: descending

  source: /_bibliography/
  bibliography: papers.bib
  bibliography_template: bib

  replace_strings: true
  join_strings: true

  details_dir: bibliography
  details_layout: bibtex.html
  details_link: Details

  query: "@*"

Next, add a layout html named bib.html under _layouts/. A sample could be found at the al-folio’s site here. Meanwhile, add the corresponding stylesheet _publications.scss to /_sass/common/components/. Then, add the following to assets/css/main.scss

@import "common/components/publications";

Next, make a new directory _bibliography/ under the root directory, and put the bibtex file papers.bib under the directory.

In addition, it is possible to have the link for coauthors by adding coauthors.yml under _data/ adapted from the al-folio’s example.

For this site, I added a few supports for coauthors, equal contribution and additional comments to each entry. You may check out _config.yml, _layouts/bib.html and /_sass/common/components/_publications.scss at my repo for details.

Site Deployment

Github Pages does not support Jekyll Scholar under the default workflow, but it is possible to host the site on Github Pages as introduced in this example. In summary, we push the source files to a separate branch to remote and keep only the generated content of the _site/ directories to the master branch.

Preliminary Steps

If this is the first time running the site, we should first create a Rakefile at the root of the repository. Then, we create and switch to a separate branch, (i.e., source) with

git checkout -b source

Automatic Deployment

We automize the deployment pipeline to Github Pages with the rake commands defined in the Rakefile.

First, we need to obtain the generated content by building the site locally with

bundle exec jekyll serve

Make sure we stay on the source branch before running the following steps. You can check the status with

git branch

We can run

rake commit

to commit the changes to the source branch locally and

rake deploy

to push the _site directory to remote master and the source to remote source.

We can also combine the two steps into one by running

rake commit_deploy

Given my limited understanding of Jekyll and front-end development, I admit that the site is still far from perfect, there are a few more possible features to include, and the notes and instructions above is not comprehensive and may contain mistakes. I’m still exploring ways to enhance the site, and I’m more than happy to receive suggestions and comments.