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.
In the end, I will give you a recommendation about website monitoring.
Let’s get started.
What is a static site generator
A static website is a website that is not generated on every request on the server-side. Every time you visit a page, the server will return the same pre-generated content.
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
- 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.
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
Initialize new Hexo project. Change “blog” to your desired project name.
hexo init blog
Go to the new folder and install project dependencies.
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/My-first-post-title.md
Let’s add some content to our first page. Copy content below to the “My-first-post-title.md” 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.
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
GitLab Pages is a simple hosting for static sites. You can host your website for free here. The main difference with a traditional hosting is that you publish a website directly from the repository.
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
At first, create a new repository on the GitLab website. Then run the command below in the project folder to initialize Git repository locally.
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
The next step is to prepare a deployment configuration.
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.
- npm install hexo-cli -g
- npm install
- hexo generate
If you want to understand what this config does, here is a simple explanation:
image- here we specify Docker image.
node:14is 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
Commit your Project
Commit is saving your changes to the local repository. To save the state of your project, run the commands below.
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
Go to your GitLab repository and open
Settings - Pages. Ensure that checkbox "Force HTTPS" is checked. Then press
New Domain button and fill in your domain name.
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
The next step is to configure DNS records. Add TXT record in a domain DNS configuration to verify domain ownership. Then add A record with IP 220.127.116.11 to map your domain to GitLab Pages.
Check the actual GitLab Pages IP.
Here is how it looks for my domain in the CloudFlare Admin panel.
Enable GitLab Runners
Settings -> CI / CD -> Shared Runners and click
Expand in Runners. Enable Shared Runners if it is disabled.
A runner is an application that runs build and deployment jobs.
Upload your website to GitLab
Upload your local changes to the remote repository with the
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
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
It is crucial to be sure your website is working. Once I updated the NodeJs version in the build configuration and then my site stopped working. So my recommendation is to use website monitoring tools. With it, you will be immediately notified about the problem.
Read my post How to monitor the website to know more.
Originally published at https://bogomolov.tech.