Setting up github pages with jekyll
This is an account of my experience setting up this web site using github
pages
and jekyll
.
It is not a tutorial on the subject, but rather a list of what I did, and why.
At first the intention was to have a set of simple pages summarising some of my projects. The usual github based address https://fredyouhanaie.github.io was sufficient. However, once I took a closer look at the features provided by github pages and jekyll, it was clear that this combination would also be suitable for publishing blog posts.
The github documentation provides instructions on various scenarios for creating a web site, depending on one’s needs. This article shows one particular path that covers the following personal requirements:
-
It should cater for use of plain text for all content, so that they can be version controlled.
-
It should allow use of own domain name with
https
access. -
It should be possible to preview the rendered pages locally before deployment to github.
About github pages and jekyll
-
The contents of the web site (github pages) are kept in a git repository that is hosted on github.
-
Github uses jekyll to generate the static web pages.
-
The static web pages are generated from text files (YAML+markdown) that follow a specific format, see https://jekyllrb.com/docs/front-matter/.
-
The html files are generated automatically, through
github actions
, whenever new changes are pushed to the repository.
Creation and the initial setup of the github pages
This was the first step. It was pretty straightforward. I just followed the instructions here.
After the set up and creation of a simple index.html
file, the web
site was up and running.
Installing jekyll on a local host (laptop)
jekyll
, a ruby based application (a gem
), is needed so that we can update
and preview the web pages locally. The github docs for installing and
configuring jekyll can be found
here
I already had ruby installed, so it was just a matter of installing jekyll:
gem install jekyll
I ran the above command as a non-root user (there is no need for root here), this resulted in the files being installed in:
$HOME/.local/share/gem/ruby/3.0.0/gems/jekyll-4.2.2
Rather than adding yet another directory to my $PATH
for the jekyll
command,
I used a symlink as follows:
cd $HOME/.local/bin
ln -sv ../share/gem/ruby/3.0.0/bin/jekyll jekyll
Creation of the basic web pages
Once jekyll was installed, the site scaffold was created within the local repo of the github pages:
jekyll new --skip-bundle .
Next, the Gemfile
needed customization, as per the github docs, which
consisted of the following two changes:
- comment out the
gem "jekyll" ...
line - uncomment the
gem "github-pages"
line, and add the version
Once updated, all the necessary packages were installed by running the bundler, the ruby package/dependency manager:
bundle config set --local path 'vendor/bundle'
bundle install
The bundle config ...
command is to force the downloaded gems to be installed
locally, rather than in the system directories. The command is what was
suggested by the bundler when bundle install
was run as a non-root user. The
vendor/
directory is not tracked by git – a .gitignore
file was generated
when jekyll new ...
was run.
Normally, we would run bundle exec jekyll serve
to generate and preview the
web pages, however, since I am using ruby 3.0.x, I also needed an additional
package:
bundle add webrick
The above added another entry, gem "webrick" ...
, to the Gemfile
. Bundler
was run again for the new gem:
bundle install
Local preview of the web site
We are now ready to preview the, currently empty, web site:
bundle exec jekyll serve
While the server is running, the web site can be viewed at
http://localhost:4000. If we modify any of the contents, such as
index.markdown
, the modification will be reflected in the web page, of course
the browser tab will need a refresh/reload.
Customization
The main configuration of the web site is kept in the _config.yml
file. Some
of the initial settings are sample site title and author names and email. These
needed to be changed.
I configured my own title, name, email etc, followed by a restart of the server.
It should be noted that changes to _config.yml
will only take effect when the
server is restarted.
Blog posts
Once the web site was operational, the initial base pages, index.markdown
and
about.markdown
, were personalized.
Next, it was just a matter of creating the blog posts in the _posts
directory.
Setting up my own hostname and https
I wanted the web site to be accessed through my own domain name, anydata.uk
.
Again, this was achieved on the github web site, following the instructions
here
It required creating two ANAME
records, anydata.uk
and www.anydata.uk
,
through my domain name service provider. Both ANAME
and CNAME
records serve
the same purpose, an explanation of the differences can be found on
Wikipedia.
When configuring the hostname on Github, a new file, CNAME
, was created and
committed to the repo by github. Withih the github settings page the box for
https
was also selected. Naturally, there was a delay before the complete
https based web site was available.
The web site is still accessible through the original github address, https://fredyouhanaie.github.io.
Other domain names
I also needed my old hostnames, anydata.co.uk
and www.anydata.co.uk
, to
point to the new web site. However, since github only allows one CNAME
per web
site, this could only be achieved with an html redirection on the original
server.
The _drafts
directory and the drafts
git branch
Jekyll expects the blog articles to be files in the _posts
directory. It will
also check for articles in the _drafts
directory, provided that the web pages
are generated with the --drafts
command line option, for example:
bundle exec jekyll serve --drafts
This feature combined with a local/private git branch called drafts
(actually
any name would suffice here) has enabled me to adopt the following process:
- Take new blog ideas (good or bad) and write them in files in the
_drafts
folder - Track the changes/revisions made to the files with git (
drafts
branch) - Review the rendered pages locally, edit/update as necessary
- Repeat the above until something worth publishing emerges
- Copy (not move) the finished article to the
_posts
directory, ready for publication
The last step involves creating a new file on the main
branch, and pushing the
changes to github.
Epilogue
For anyone considering a similar project, the supporting documentation provided by Github and Jekyll are pretty good, even for the impatient! The occasional internet search also helps ;-)
So, what’s the point of this article? Well, it provides one specific scenario for anyone in a similar position. And, more specifically, it has allowed me to aquaint myself with the toolset :-)