Static website creation using Jekyll and it’s hosting using Gitlab

Intro

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:
gem install bundler jekyll
  • go to the folder in which you want to create directory with your website and execute:
jekyll new project_name
  • the folder with the static website has to be created so you can go into:
cd project_name
  • 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:
bundle exec jekyll serve

After this steps completed website has to be hosted in localhost:4000. If it does not appear and you get 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 localhost:4000\value_from_baseurl_property

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 Gemfile by adding next ling:
gem "minimal-mistakes-jekyll"
  • run the command to install theme (should be executed in your project’s root directory):
bundle install
  • replace value of the theme parameter in _config.yml file:
theme: minimal-mistakes-jekyll
  • execute command:
bundle exec jekyll serve

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.

Deployment process

The deployment process using Gitlab is very easy and can be completed in a few steps:

  • create .gitlab-ci.yml file with the next content (as an example):
  image: ruby:2.3.7-jessie
  variables:
    LC_ALL: "C.UTF-8"
    LANG: "en_US.UTF-8"
    LANGUAGE: "en_US.UTF-8"
  
  pages:
    stage: deploy
    script:
      - bundle install
      - bundle exec jekyll build -d public
    artifacts:
      paths:
      - public

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. This public folder will be referring from implicit deployjob.

  • 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 switch to Mojave. The installation went well, but then bundle stopped to work because it was missing some library.

  /System/Library/Frameworks/Ruby.framework/Versions/2.3/usr/bin/ruby -r ./siteconf20180912-38268-nmeu8e.rb extconf.rb
  mkmf.rb can't find header files for ruby at /System/Library/Frameworks/Ruby.framework/Versions/2.3/usr/lib/ruby/include/ruby.h
  
  extconf failed, exit code 1
  
  Gem files will remain installed in /Library/Ruby/Gems/2.3.0/gems/eventmachine-1.2.7 for inspection.
  Results logged to /Library/Ruby/Gems/2.3.0/extensions/universal-darwin-17/2.3.0/eventmachine-1.2.7/gem_make.out

Core problem: gem was missing dev mode.

Solution: so we need to install it by executing this commands:

      xcode-select --install
      xcodebuild -license

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:

  Conversion error: Jekyll::Converters::Scss encountered an error while converting 'assets/css/main.scss':
                      Invalid US-ASCII character "\xE2" on line 54

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:

    variables:
      LC_ALL: "C.UTF-8"
      LANG: "en_US.UTF-8"
      LANGUAGE: "en_US.UTF-8"

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 test/html.

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 https://your_gitlab_login.gitlab.com/your_repo_name where 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 _config.yml:

  baseurl: "/your_repo_name"

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.

Conclusion

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.

Updated:

You May Also Enjoy