Add a static website to the repo

[lakruzz]

Let's add som real code, that requires a development environment and a deploy process

Note

☝️ Learning goals in this issue

• Add a static Jekyll website to the repo
• Configure it to it's exact purpose; GitHub Pages
• Detach the site theme from source (a gem) to become a remote reference to a GitHub repo
• Configure the repo to host the site on GitHub Pages
• Add a GitHub Action workflow that automatically build and deploys to a live production environment

---

Jekyll is a multi-compliler that builds html from a combination of MarkDown, yaml and Liquid and CSSfrom SASS (or SCSS if you prefer). It is originally developed by GitHub with the specific purpose of supporting GitHub pages.

Jekyll itself is build in Ruby, so in the exercises in this issue we will get into som ruby-lingo. The modules or packages in Ruby are called gems and the package manager is called bundler. The dependencies are managed in a gemfile. The Jekyll site itself is configured in the _config.yml file in the root the directory that holds the source - which is mainly .md - MarkDown files. in a typical static web style that contains FrontMatter, which means that the first section of the file is dedicated to yaml.

There - that's it. Now you know all there is to it.

The following exercises all take place in the CodeSpace you created for this repository

🏋️‍♀️ Exercise

• Add a new jekyll site to a separate docs folder

In the code space create a new jekyll site in a new docs folder

jekyll new --skip-bundle --force ./docs

Go to the new docs repo and install the gems and build and serve the site

cd docs
bundle update && bundle install
bundle exec jekyll serve

The site will come up and run on port 4000 have a look at it.

Let's record this before we move on

git add -A
git commit -m "I setup a jekyll site in my repo"

🏋️‍♀️ Exercise

• Alter the gemfile to use the github-pages gem
• Add any missing gems to the gemfile

There are a few changes it makes sense to do, now we know, that the jekyll site is going to be hosted from GitHub pages:

In the ./docs/gemfile there is a recommendation in the comments (lines 10-14):

gem "jekyll", "~> 4.3.3"
# This is the default theme for new Jekyll sites. You may change this to anything you like.
gem "minima", "~> 2.5"
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
# gem "github-pages", group: :jekyll_plugins

Do the change suggested, so loose the jekyll gem and go with the github-pages gem - like this:

# gem "jekyll", "~> 4.3.3"
# This is the default theme for new Jekyll sites. You may change this to anything you like.
gem "minima", "~> 2.5"
# If you want to use GitHub Pages, remove the "gem "jekyll"" above and
# uncomment the line below. To upgrade, run `bundle update github-pages`.
gem "github-pages", group: :jekyll_plugins

Update the gems and run again

bundle update && bundle install
bundle exec jekyll serve

Aaargh! it fails!

The gist of the error message is this:

Warning

cannot load such file -- webrick (LoadError)

This must be fixed in the ./docs/gemfile too and it's quite simple. just add the missing gem to the jekyll_plugins group - the end result is then

group :jekyll_plugins do
  gem "jekyll-feed", "~> 0.12"
  gem "webrick"
end

Go again:

bundle update && bundle install
bundle exec jekyll serve

Yeah! The site is back up on port 4000

Let's record this too:

git add -A
git commit -m "The jekyll site now builds with the github-pages gem"

🏋️‍♀️ Exercise

• Change the minima theme from sourced in a gem to become a remote reference

One final step I personally like better - but strictly you can skip this if you don't care.

In the ./docs/_config.yml file you'll see that the theme used is minima

theme: minima

This syntax uses an installed gem to source the theme. I want to source the theme directly from GitHub instead (the theme is hosted on jekyll/minima). This way, I can easily create a fork of the theme and point to that - and I have full control over all the content. For now, I'm not forking the theme, I'm just pointing to the community maintained theme directly. Change the theme to use a remote_theme like this:

remote_theme: jekyll/minima

Test to see it work. When you serve a jekyll site it automatically monitors any file change in the directory and rebuilds immidiately. However; changes in the _config.yml file is not monitored. so you will have to stop the server with ^CTRL+C and re-start it:

bundle exec jekyll serve

Happy? OK then - over and out;

git add -A
git commit -m "Using the remote hosted theme"
git push

🏋️‍♀️ Exercise

• In the repos settings configure the repo to host GitHub pages.
• Add a Github Action workflow.

Go to github.com and browse to your repo.

Tip

The gh CLI actually has a command that will take you directly to the repo's web site. Try...

gh browse

Go to Settings >> Pages.

In the section Build and Deployment add a GitHub action and in the workflow file locate the actions/jekyll-build-page action in the Build with Jekyll step. Change the source from ./ to `./docs``

👇 See a screen recording of hos it's done

Go to the Actions tan and see the build - brows to your website when it's done.