Gitlab and Hexo

In

Setting up a Gitlab page with a NodeJS blogging system

I started a new project in order to generate a static web page, a small blog to store and share my programming notes and cheatsheets which I write by default in Markdown. There are several alternatives, but I chose to use Hexo since I wanted to try the new NodeJS version.

Software used

  • Git: version management.
  • NVM: you can manage the NodeJs version with this system, so you don’t have to endure the installing and uninstalling process each time you work in a different project. There is also a NVM Windows installer.
  • VSCodium: a free open source version of Visual Studio Code. Microsoft budles it with some extra layers such as telemetry and who knows what else, and this version is free from all that.

Environment

❗ Note: while I prefer using the console when I’m not doing any major merge, you can always use a GUI Git system.

First I will download the latest NodeJs version via NPM and check it out.

1
2
nvm install
nvm list

To get the code into my local system.

1
git clone https://gitlab.com/usuario/code-notepad

Then I get the Hexo command line interface via npm, the NodeJs default package manager.

1
npm install hexo-cli -g

And now, welcome to Hexo.

Creating the blog

First we initialize the blog.

1
2
3
hexo init blog
cd blog
npm install

Then if we want to have assets (e.g. images) for each post, we should set the right variable for that. It is stored in _config.yml.

1
post_asset_folder: true

And finally we deploy in single command to check everything works as we want to.

1
hexo server

Customization with themes and plugins

We may want to use a custom theme. It’s as easy as to go the repository, download it an store it in the themes folder.

I love mermaidJS diagrams, as they provide an easy way to create diagrams while taking notes, and they are portable. Hence I added a pluging to been able to use them in my posts via npm.

1
npm i hexo-filter-mermaidjs

And then I configured them.

  1. In _config.yml, on the plugins section I added.

    1
    2
    3
    4
    5
    6
    # mermaid chart 
    mermaid: ## mermaid url https://github.com/knsv/mermaid 
      enable: true  # default true 
      version: "7.1.2" # default v7.1.2 
      options:
        #startOnload: true  // default true

  2. And in the footer.ejs from my theme template.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    <% if (theme.mermaid.enable) { %>
      <script src='https://unpkg.com/mermaid@<%= 
        theme.mermaid.version %>/dist/mermaid.min.js'></script>
      <script>
        if (window.mermaid) {
          mermaid.initialize({theme: 'forest'});
        }
      </script>
    <% } %>

Adding the CI

Finally I added the CI (Continuous Integration) file, in the root of the directory: .gitlab-ci.yml. This file will use a docker container with a NodeJS 10.15.3 image, where it will install Hexo, build the packages, generate the pageand deploy the content in Gitlab pages.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
image: node:10.15.3

cache:
  paths:
    - node_modules/

before_script:
  - npm install hexo-cli -g
  - test -e package.json && npm install
  - hexo generate

pages:
  script:
    - hexo generate
  artifacts:
    paths:
      - public
  only:
    - master

With this we have the skeleton ready, so now we only need to upload the code to Gitlab, and that will automatically launch the process getting the page to something similar to this: https://angelesbroullon.gitlab.io/code-notepad/.

1
2
git commit -a -m "Init blog system"
git push

How to blog

We can create posts from the source folder by writing them using Markdown syntaxn.

1
2
cd source
hexo new post "My firts post"

This will generate a markdown file with the following header, which will allow us to sort out the content.

1
2
3
4
5
---
title: My fist post
date: 2018-04-17 10:00:00
tags: [Tag1, Tag2]
---

We can store images in the folder which was created with the same name as the post, using the following syntax (e.g. in the “My first post” folder we store an image image.jpg):

1
2
{% asset_img "image.jpg" "Image description
" %}

Then we commit, push, and Gitlab will do its magic.