In this post I document the process I went through
to set up a peronsal web site with a structure
similar to the
used by many academics.
I’m writing the post for my future self,
and for you if you want to do the same.
Why would you bother?
I wanted a site similar in style to
with links in the sidebar to Google Scholar, OrcID, etc.,
and the ability to use
jekyll’s “collections” feature
to easily organize publications, talks and teaching.
But I also wanted the flexibility to change themes,
which is not easy to do with
I love to support Python libraries like
and some of the themes are very versatile,
like their version of
minimal-mistakes and other
jekyll themes just look better
to my (untrained) eye.
Last but not least, this is a fun exercise in using libraries in a language besides Python. It’s interesting to experience the tooling in the ecosystems of other programming languages.
How did we get here?
I’ve had a personal web page for sometime that I set up with
pelican, a static web page generator in Python.
Basically I adopted my approach from the one Jake Vanderplas took for his
“pythonic perambulations” blog.
However I wasn’t happy with how my page looked
(which has nothing to do with Jake Vanderplas,
and everything to do with my moribund graphic design and css/html skillz).
And it was time to update my site anyway.
Recently I noticed a collaborator had set up their own personal site using the
developed by Stuart Geiger.
academicpages is great if you are trying to survive in academia
and you don’t have time to bother learning how to use a static site generator.
academicpages you just want to follow a couple steps to add your own
content to some existing template, to easily get a site.
academicpages is a fork of
a very popular theme for the
jekyyl is a static site generator written in
ruby programming language.
You can think of it as analogous to
pelican in Python
(or Ruby developers might tell me that
pelican is analgous to
One advantage of using
jekyll is that
GitHub really likes
letting developers easily create web pages for themselves or documentation
for their projects through the
GitHub Pages service.
And it’s free, another plus for academics.
Stuart modified the
minimal-mistakes theme in such a way
that other academics could simply fork its repo
on GitHub and use the web interface to add their own content,
without needing to know how to use
or how to use any developer tools like
So I knew I wanted a site like
but I also knew there were things I wanted to modify, such as the theme / template.
There’s little documentation in the
academicpages guide about
what changes were made to the
minimal-mistakes theme, and why.
How did Stuart evolve the template from your standard
minimal blog page to a very specific set-up for academics?
Unique features of
that it lands on the
about page and shows a profile in the sidebar
with links to academia specific sites, and
includes tabs like “publications”, “talks”, etc.?
I tried looking at the
git commit history but couldn’t
piece it together.
I figured there couldn’t be too too many steps
to setting up a similar site on my own.
Step-by-step guide to developing your own ‘academicpages’
Here’s the summary version first so you know what you’re getting into:
- set up a
- make the landing page be your about page
- make the sidebar show your profile with links
- add links to publications, talks, etc., in the nav bar at the top of the page
Setting up a development environment
This is a thing that might be new to academics
not familiar with software engineering,
ruby devs have worked really hard
to make it easy.
- set up a basic environment for working with
- then I followed the directions for managing dependencies with
bundlerso that I could install the
minimal-mistakestemplate as a
geminstead of forking their repo and modifying it
Making the “landing page” be your “about” page
This is the first thing that’s specific to our site design.
- use the
redirectplugin so that the site lands on “about”
- add an
about.md– make sure you copy the YAML front matter from
- make sure
_config.ymlspecifies defaults for
pagesso that your theme gets applied to this
- I copied the
#defaultssection from the
- I copied the
Making the sidebar show your profile, with links
Now we’re cooking with
academicpages gas! Or something
- to make the author profile in the sidebar render all the links that are
academicpagesbut not in
minimal-mistakes, i.e. academia specific things like a Google Scholar page, ORCID profile, etc., you’ll need to add an
_includesdirectory. Basically I copied the
minimal-mistakesand then added the relevant if-then statements in the
- for things like an author pic, I added them in
assets/images/– I think this is consider “idiomatic Jekyll” even though the
academicpagesrepo just has an
imagesfolder in its root. Doesn’t matter too much as long as you specify the correct relative path in your
Adding links to publications, talks, etc., in the masthead nav bar
academicpages are the links in the navigation bar
at the top of the page to pages with lists of publications, talks,
and so on.
If you want the same thing, there’s two things you’ll need to do:
- you’ll need to copy the ‘navigation.yml’ file from
academicpages, placing it in a
data/subfolder in your project root, and modify it as you see fit.
- add two related sections in your
This is explained very briefly in the
here’s a quick explainer of how it all works.
minimal-mistakes lets you add links to the masthead
by supplying a file called
This is a
standard approach in
There are other uses for data files.
What’s specific to
minimal-mistakes is that you
add these links to the nav bar by specifying a
navigation.yml, as described here:
In the case of
the links have the names of the specific sections
navigation.yml with the keys “publications”, “talks”, etc.
Coda: publishing, etc.
After making the changes just described, I had a site
with a structure similar to
To actually publish the site, I still use a workflow similar to
what Jake Vanderplas uses for his blog:
This centers around a Makefile with commands for
The key thing that makes it easy to publish to Github Pages is to
ghp-import package, as suggested by the
jekyll gets special treatment on GitHub
so it’s kind of overkill,
but I still like having a separate repo that I just push the
.html and .css files to without thinking about it.
So this is how I have my site set up now! Stay tuned for it to change suddenly, because as a developer I love to spend hours farting around with tools that let me avoid real work. I’ll keep this post up for posterity anyway.