How to create a blog using Hexo static site generator and free web hosting on GitLab Pages

This is a complete tutorial on how to create a blog using a static website generator and free web hosting in 2021. It is better to have at least basic programming experience to proceed with the tutorial.

We will use Hexo as a blog framework, GitLab Pages as a free hosting with HTTPS and a custom domain, Node JS and Git.

In the end, I will give you a recommendation about website monitoring.

Let’s get started.

What is a static site generator

Dynamic web pages, in contrast, may generate new content on every request. It may get data from the database or use business logic on the server-side to generate content.

A static site generator is an application that generates a website from templates or any other source. For example, Hexo generates HTML files from Markdown documents.

Choose the best static website generator

Here are the most known generators I found with some stats from Github. Stats actual for March 2021.


  • used by 83.3K, 856 watchers
  • 32.4K stars, 10.46 avg. stars/day
  • 83 open issues, 3650 total issues
  • 152 contributors, 956 total pull requests
  • primary language is Javascript
  • last release version is 5.4.0


  • used by 65K, 1059 watchers
  • 50.7K stars, 18.02 avg. stars/day
  • 592 open issues, 5223 total issues
  • 700 contributors, 3052 total pull requests
  • primary language is Go
  • last release version is 0.81.0


  • used by 1.1M, 1473 watchers
  • 42.4K stars, 9.35 avg. stars/day
  • 80 open issues, 4367 total issues
  • 949 contributors, 4060 total pull requests
  • primary language is Ruby
  • last release version 4.2.0

Jekyll looks the best based on these simple stats. Hugo’s major version number is still 0, and it has more issues than others.

The main reason for me is a primary language. I am using NodeJS a lot, so this technology may be easier for me in case of any bugs or whenever I need to extend some functionality with a plugin.

That’s why I choose Hexo there.

Hexo installation

Then install Hexo globally. Run this command to install hexo-cli package.

npm install -g hexo-cli

I am using Hexo version 5.4.0.

Create a new Project with Hexo

hexo init blog

Go to the new folder and install project dependencies.

cd blog
npm install

Create a simple post with the command below.

hexo new post "My first post title"

You will see the new post file in the output.

INFO  Created: /app/source/_posts/

Let’s add some content to our first page. Copy content below to the “” file.

title: My first post title
date: 2021-03-16 06:19:49
# This is H1 header

This is content

Next, run Hexo server to preview your website and post. Enter the command below in your terminal to run a server locally.

hexo server

It will generate your website and serve generated files locally. So you can check how your website will look. If no errors, you will see this output:

INFO  Hexo is running at http://localhost:4000 . Press Ctrl+C to stop.

Open provided ULR in a browser and check your website.

That’s it. Our simple website is ready to deploy.

For more information see Hexo documentation. Otherwise, use the help command instead of documentation. Just run hexo help in the terminal to see all available commands.

Let’s continue with the deployment process to GitLab Pages.

What is GitLab Pages

We will use GitLab Pages here as a free web hosting in the tutorial and set up it with a custom domain and HTTPS.

Here is the main alternative if you want to have a look: GitHub Pages.

Create a new GitLab repository

git init

Add your created remote GitLab repository to your local repository with this command:

git remote add origin <your_repository_link>

You can get your repository link from the GitLab new repository. After you created the repository, scroll down a little, and you will see the commands listed under the “Push an existing folder” section.

Just copy commands from there. Here is my test repository commands screenshot as an example:

Let’s proceed with a deployment configuration.

Add GitLab Deployment Configuration to the Project

Hexo is a static website generator. It doesn’t store generated HTML files in the Git repository. That’s why we need to re-generate files on every website update.

Static files will be generated automatically at the GitLab side, every time you send updates to the remote repository with GitLab Continuous Delivery (CD) tool.

Add the new file .gitlab-ci.yml to the root of your project with the content below.

image: node:14
- node_modules/

- npm install hexo-cli -g
- npm install

- hexo generate
- public
- master

If you want to understand what this config does, here is a simple explanation:

  • image - here we specify Docker image. node:14 is the official Node JS Docker image with NodeJS version 14
  • cache:path: - contains a folder to cache between jobs
  • before_script - contains scripts we want to run before any job
  • pages - contains job configuration
  • pages:script - script to run in the job. We will generate static pages with Hexo here
  • artifacts:paths - this folder with a generated website will be hosted at GitLab Pages and will be available in GitLab UI after the job finishes
  • only - conditions to run jobs, i.e. run this job only on the master branch

Actual Hexo config
Actual GitLab yaml reference

Commit your Project

git add --all
git commit -m "Commit message, describing your changes"

Now we are ready for the deployment. Next, we need to set up the GitLab project.

Create a Page on GitLab

Make your page available: go to Settings - General, click to Visibility, project features, permissions and change configuration for Pages to Everyone

Set up DNS records

Check the actual GitLab Pages IP.

Here is how it looks for my domain in the CloudFlare Admin panel.

Enable GitLab Runners

A runner is an application that runs build and deployment jobs.

Upload your website to GitLab

git push -u origin master

After pushing GitLab CD automatically generate static files and update your website. You can see the running job in project Settings - Pipelines or Jobs.

It may take up to 30 minutes before the site is available after the first deployment. Then your website should be available by your domain.

Also, you can check it by GitLab URL. You can check URLs in the Settings - Pages.

Website monitoring recommendation

Read my post How to monitor the website to know more.

Originally published at

Web Developer | PHP Certified | Digital Nomad