Static website creation using Jekyll and it’s hosting using Gitlab
Recently I opened for myself the interesting world of static websites generators. They help to do easy conversion of markdown files into html. I found it really interesting as far as I am not really good at building pages and css styling of them. At the same time these generators allows you to work with the convenient format of markdown files and then convert those files into beautiful html pages using already created templates.
So I would say that these generators are a really easy way to build your website if you don’t want to mess with frontend part a lot.
Among several of static website generators I chose Jekyll because it has one of the biggest community already, pretty good documentation. I heard a lot of nice things about it and my friend used it to build his website a year ago. So the decision was made to give it a try.
Starting with Jekyll
To start your static website with Jekyll all you need to do is:
- install bundler and jekyll with:
- go to the folder in which you want to create directory with your website and execute:
- the folder with the static website has to be created so you can go into:
- inside the directory you will find bunch of folders as far as other files like Gemfile, index.html and so on
- the last step you need to do is to start hosting of your static website locally:
After this steps completed website has to be hosted in
localhost:4000. If it does not appear and
Not found response, then you need to check
baseurl field in
_config.yml - it has to
be empty. If it is not empty then open url
Hopefully you finished all the steps and you see the website.
Using jekyll template
One of the most beautiful things in static website generators is that we can use prebuild templates to build our website in a fast and easy maner. These templates represent prebuild style, pages structure and scripts needed to make working website. The only thing we need to do is to add content and make logical structure of the data.
As I mentioned above the Jekyll’s community is pretty big one. That’s why it is easy to find a lot of various themes. For example you can find them on Jekyll Themes org, Jekyll Themes io , Wow themes an on many other sites.
The installation of the theme may vary from one to another, so you have to read the docs for each team. In my case Minimal Mistakes Theme was used and the installation process looked like:
- include theme installation in
Gemfileby adding next ling:
- run the command to install theme (should be executed in your project’s root directory):
- replace value of the
- execute command:
That is it you website has to have new theme. But be aware that each theme requires a lot of additional changes because layouts might have different names, different properties might be used so do not hesitate to look into docs of each theme.
Gitlab pages deployment
Small introduction to gitlab pages
You probably already know about hosting using github and gitlab, but I would like to share my experience with it because there were a few moments when I stuck and was searching for solution.
Gitlab as well as GitHub gives us a great possibility to host static website for free, but provides more features like instances for building website (CI/CD feature), hosting website while the project is private and more others
I found it really useful to have CI/CD tools and hosting website feature in one place - so I have a feeling of really robust continuous delivery process.
The deployment process using Gitlab is very easy and can be completed in a few steps:
.gitlab-ci.ymlfile with the next content (as an example):
Be aware that you have to use
pages stage name as far as the name of the folder which
will be used to store website after building it should be
public folder will
be referring from implicit
- commit changes to you gitlab repository. The pipeline has to be started and in a few minutes
it will be finished. The url of your website can be found in
Settings > Pages. If everything is ok in a few minutes (not instantaneously) your website should be available.
You can also find really good description about how to set up gitlab pages here
Problems I faced with
It would be to easy to say that it was it. During the process of setting up Jekyll and Gitlab pages I faced with a few problems.
Problem with gem dev env
The prehistory: I started using Jekyll with macOS
HighSierra installed, but then decided to
Mojave. The installation went well, but then
bundle stopped to work because it was
missing some library.
Core problem: gem was missing dev mode.
Solution: so we need to install it by executing this commands:
The first line installs xcode-select. The second line accept the license. After these steps bundle started working again.
Problem with locale
The prehistory: When everything looked fine locally, it was time to deploy website using gitlab.
Then different problems appear. The first one:
jekyll bundle -d public did not work properly because it
could not read
main.css file - symbol was unknown:
Core problem: the docker container which is used by the job (in my case
ruby:2.3.7), is using
a different locale.
Solution: so I had to set those variables directly in the docker container:
Problem with baseurl
The prehistory: the other problem appeared when I finally deployed everything. The site was in
place, but without styles and links did not work at all. The reason was found in the console: browser
cannot load files because of MIME type was
Core problem: after investigation I realized that files cannot be reached even directly which
means that the url was not right or they had no permission to be exposed to the world. The core
reason is that gitlab pages deploys your website under
repo_name is used as baseUrl. At the same time all files in the website had urls
without this baseUrl.
Solution: Jekyll provides easy way to set baseUrl by updating the value in
Then restart jekyll and commit these changes to gitlab repo to start the pipeline. When pipeline finishes its work, website has to work well: with styles and proper links.
Eventually after fixing these issues the site was successfully deployed to gitlab. As for me the simplicity and costless of this approach for having static website make gitlab pages and Jekyll a really great alternative for most cases of simple sites.
I hope you will find this article useful for you.