2022 Week 38 How to create a static website with Jekyll and deploy it on GitHubPages

20 Sep 2022 - Aaron

Prerequisits

Install Git
Install Ruby
Install Jekyll and Bundler

$ gem install jekyll bundler

GitHub

Create a GitHub-account
Create a repository on GitHub
(It has to be public if you use GitHub Free, note that your code will be visible to everyone!)

Local Repository

Clone the repository to a local directory:
ssh

$ git clone --recursive SSH_URL

https

$ git -c http.sslVerify=false clone --recursive HTTPS_URL

Directories

Create two directories: docs and localDev.

$ mkdir docs $ mkdir localDev

docs will contain the content of the website later on.
localDev will contain our Jekyll project.

Create Jekyll Project

Move to the localDev-directory:

$ cd localDev

Create a new Jekyll-project at localDev-directory:

$ jekyll new --skip-bundle .

(make sure you got the dot)

Edit Gemfile

Open the Gemfile that Jekyll created and comment out (#) the line which starts with gem "jekyll"
Add the github-pages gem by editing the line starting with # gem "github-pages".
Change this line (# gem "github-pages") to:
gem "github-pages", "~> GITHUB-PAGES-VERSION", group: :jekyll_plugins
You can find the actual version of GitHub-pages here.
Now save and close the Gemfile.

Install bundle

Now still being at the localDev-directory, install the bundle:

$ bundle install

Optionally you can make changes at the _config.yml file.

Learn Jekyll

Follow this guide to learn Jekyll. Make sure that all files and directories you create are in the localDev-directory.
Note that building locally will not work according to commenting out gem "Jekyll" at the Gemfile. (Atm I didn't check if this is right)
If it is, you have to not comment it out and do bundle install again. Afterwards you can test locally with jekyll serve.

Build Project

After creating all necessary files and dirs, you can make a production build:
Note that all files at _site will be cleared!

$ JEKYLL_ENV=production bundle exec jekyll build

Your Jekyll-project was now build and stored at _site.
Clear your docs-directory:

$ rm -r ../docs/*

Now move the content of the localDev/_site to docs:

$ cp -r _site/* ../docs

And push your changes to your central GitHub-Repository.

Publish Website

Now publish your repository on GitHub Pages.
Select your branch and as folder /docs and hit Save.
Now you have to wait, this can take up to 10 minutes.
On the top of the page a box will appear with the url of your website.