Jekyll nicely integrates with GitHub Pages.
However, this comes with rules that forbid using Jekyll plugins but for authorized ones.
We will see here how to deal with this limit.
Note: I am discussing here about User pages on GitHub Pages.
For Project pages things are a bit different. For example for User pages, pages are on a
For Project pages, pages are on a
If you want, e.g., to use the Jekyll-Scholar plugin
(to generate pages from
.bib BibTeX reference files),
you will have either not to use GitHub Pages
(make a simple
my-web-pages repository and sync your pages with a Web server somewhere else)
or to shortcut the GitHub Pages workflow. This is what we will do here.
This part is based on Olivier Barais’s template, itself based on Walter Rudametkin’s template. I chose not to fork their templates here since my site structure is different and I also wanted to build things from scratch to explain how to integrate elements one by one. Yet, without them, shortcutting the GitHub Pages workflow would certainly have been much more complicated. Please consider forking their templates that are much more advanced than mine for the moment.
How things work with the GitHub Pages workflow
Jekyll takes its sources, i.e., files and specific directories (ones beginning by
_ in short) in the current path
and compute pages in subdirectory
_src. See the Jekyll directory structure here.
GitHub Pages require that your Jekyll sources are in the root directory of
Then it runs Jekyll and deploys the resulting pages to
If you want to write your pages directly (e.g, without templates) you would have to put them
at the root of the
username.github.io repository and add a
.nojekyll empty file to tell GitHub Pages not to
run Jekyll each time you push things. This is very important if you have directories beginning with
they have a special treatment with Jekyll (they are not deployed on the Web site).
Putting things together
srcdirectory at the root (of the repository) containing the Jekyll sources
edit files in
srcas usual, and commit+push them to GitHub regularly
have Jekyll run on these sources and place them in
“build” the site regularly by copying the pages from
src/_siteto the root of the repository, and then commit+push the new versions of these to GitHub
For this one has two scripts that automate steps 3. and 4.
Step 3. is achieved by
src/run-jekyll.sh. You can have it run in background while doing steps 1. and 2.
Step 4. is achieved by
Note: Jekyll supports the possibility to tell in its configuration file where are the source and the target directories. I may use this in the future to simplify things and avoid some file copying.