You can use jekyll to build your own static web site for every github repository.


It is a powerfull tool enabling to combine Liquid template language, markdown and html. Github repository is by default built from a branch called gh-pages, the easiest is to follow this convention (you can tweak this in your repository under Settings > Pages > Source).

Installation

For all OS set the folder (otherwise you will risk rights issues) export BUNDLE_PATH=~/.gems You can refer to jekyll with bundler for further details.

a. Ubuntu

sudo apt update
sudo apt install ruby-full
sudo apt install bundler

You can check ruby is correctly installed

$ruby --version
$ruby 3.0.2p107 (2021-07-07 revision 0db68f0233) [x86_64-linux-gnu]

b. MacOS

You need to install ruby (which will include bundler). You can do so using homebrew

brew install ruby@2.7

NB: it did not work for me with latest Ruby 3.x but worked like a charm with 2.7

Add ruby and its gems to your path

echo 'export PATH="/usr/local/lib/ruby/gems/2.7.0/bin:$PATH"' >> /Users/username/.bash_profile
echo 'export PATH="/usr/local/opt/ruby@2.7:$PATH"' >> /Users/username/.bash_profile

refresh your environment

source ~/.bash_profile

c. Fedora

You can follow instructions from https://gainanov.pro/eng-blog/linux/installing-jekyll-fedora/

sudo dnf install ImageMagick

Scaffolding

Go to the directory you want to create your repository website in

mkdir <your_new_repo_folder> && cd <your_new_repo_folder>
bundle init
sudo bundler add jekyll
bundler exec jekyll new --force --skip-bundle .

Test

You can run locally your website and adjust what’s needed

bundler install
bundler exec jekyll serve --livereload

It will print the url you can access to visualise your site.

Look and Feel

To go beyond this simple introduction you may want to leverage existing templates, do not hesitate to have a look pick one or create your own.

Troubleshooting

  • the site does not refresh once pushed on ghithub
    • you can check under you repository Settings > Pages If everything went well you should see below message, otherwise you may get a hint of the issue


    • also if you notice your site is not refreshing, you can try to push an empty commit to force a refresh
      git commit -m 'rebuild pages' --allow-empty
  git push origin gh-pages
  • install ImageMagick for al-folio theme
sudo apt install pkg-config
sudo apt-get install imagemagick libmagickwand-dev