Filippo Merlo posts
About Posts Repos

Build a static website with Jekyll🧪 and GitHub-Pages

March 03, 2026 5 min read

To create a static site that will be hosted on GitHub Pages, using Jekyll as a generator, we need first to:

If we want to use a custom domain instead of the default $username.github.io, we need to create a CNAME file with inside only your custom domain, e.g.

mycustomdomain.org

and in the settings of your domain provider, we must add rules for GitHub-Pages, as follows:

HOST TYPE DATA
www CNAME $username.github.io
@ A 185.199.108.153
@ A 185.199.109.153
@ A 185.199.110.153
@ A 185.199.111.153
@ AAAA 2606:50c0:8000:0:0:0:0:153
@ AAAA 2606:50c0:8001:0:0:0:0:153
@ AAAA 2606:50c0:8002:0:0:0:0:153
@ AAAA 2606:50c0:8003:0:0:0:0:153

to set the CNAME redirection and the IPv4 and IPv6 rules. If it’s asked to specify a TTL value, we can use 4 hrs which is normally the default one, and for the priority, we leave it as default or not set (N/A).

Now, because we’re using Jekyll as a static website generator, it’s possible that some plugins specified in the Gemfile are not supported by GitHub Pages. We can use the following official GitHub’s Action, by going on the Actions tab of our repository, search for Jekyll and let it automatically configure for us, or going to jekyll-build-pages and manually add it as a new workflow.

Last but not least, we must specify a title, url and baseurl, in my case:

title: Filippo Merlo
url: "https://crisis82.me"
baseurl: ""

which are fields required by the build workflow to succeed. Note that if you used a CNAME it’s preferable to use the same URL in the _config.yml file instead of the GitHub one.

Do not forget to check that HTTPS is enabled in the GitHub repository settings. This should be automatic, still if we bought a fresh new domain, this option may not be available immediately due to certificates synchronization timings.

After have committed and pushed the changes, the site will be automatically build and served 🥳.

Testing🔧

To test our website locally, we need to install Ruby, so in my case for Void Linux is

xbps-install -su make ruby ruby-build ruby-devel

Before using Ruby’s packager manager called gem, we need to export a shell variable to allow gem to know where files will be stored for our USER, otherwise will default to a global installation and we will end with permission errors. So we can add

export GEM_HOME=$HOME/.gem

to our shell configuration file, in my case ZSH, so in .zshenv, .zprofile or .zshrc.

Now we can run gem install bundler to install bundler, which is a Jekyll version manager that installs and manage the Jekyll plugins specified in our Gemfile.

Finally we can run bundle install to install the plugins and bundle exec jekyll serve to locally build and serve our website at http://127.0.0.1:4000.

Suggestions

Some useful plugins are:

---
permalink: /robots.txt
---
User-agent: *
Disallow:

Sitemap: https://crisis82.me/sitemap.xml

For a faster indexing in most common search engines, it’s useful to manually index your website with Google Search Console and Bing Webmaster Tools. This step it’s very straightforward because we only need to log in with a Google account, provide our website link and verify that we’re the owner following the steps suggested. Usually this means that we need to create a new plaintext entry with the unique identifier provided in the DNS rules of your domain provider (like done previously). After having completed this step, we can provide the sitemap.xml location of our website, to allow page indexing. The same process can be done with Bing, but if we have already indexed our website with Google Search Console, the process for Bing is even simpler, because we only need to log in with the same Google account and import the data from Google Search Console. After the import, just check if the sitemap has been imported, because for me that was not the case even thought it was specified otherwise. Now we just need to wait 1 or 2 days to allow Google/Bing to index your website.