This is an account of my experience setting up this web site using
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
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
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:
Rather than adding yet another directory to my
$PATH for the
I used a symlink as follows:
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 .
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 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
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
bundle add webrick
The above added another entry,
gem "webrick" ..., to the
was run again for the new gem:
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.
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.
Once the web site was operational, the initial base pages,
about.markdown, were personalized.
Next, it was just a matter of creating the blog posts in the
Setting up my own hostname and https
I wanted the web site to be accessed through my own domain name,
Again, this was achieved on the github web site, following the instructions
It required creating two
through my domain name service provider. Both
CNAME records serve
the same purpose, an explanation of the differences can be found on
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,
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
_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
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
- Track the changes/revisions made to the files with git (
- 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
_postsdirectory, ready for publication
The last step involves creating a new file on the
main branch, and pushing the
changes to github.
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 :-)