curben
/
blog
mirror of https://gitlab.com/curben/blog
1
0
Fork 0
Code Issues Releases Wiki Activity
blog/source/_posts/how-to-create-a-hexo-blog.md

6.8 KiB
Raw Blame History

title date lastUpdated tags
How to create a Hexo blog on GitLab Pages 2018-09-21 00:00:00 2018-11-10 00:00:00
Hexo
GitLab

Create a website/blog using Hexo on GitLab Pages for free using the following guide. Refer to my {% post_link hexo-blog-github 'another guide' %} for GitHub Pages.

GitLab project

  1. Register a free GitLab account or use your current one.

  2. Fork the repo of this blog.

  3. Shared Runners should be enabled. Go to your (forked) project Settings -> CI / CD -> Shared Runners.

  4. Change project website to a user website. This is so that the website's home page is username.gitlab.io, instead of username.gitlab.io/hexo. Go to Settings -> General -> Advanced -> Rename repository. Change the Path to username.gitlab.io, where username is your username on GitLab.

  5. You can start writing a new post straight away without installing Hexo. You still need to change the blog's name and favicon though (how-to).

    1. To create a new post (through GitLab.com), create a new <post-title>.md file in source/_posts folder.
    2. Start with the following header/front-matter:
    ---
title: Test page
date: yyyy-mm-dd hh:mm:ss
tags:
categories:
---
    1. Write your post after the second --- using Markdown style.

  6. After you create a new post, the website can be accessed on username.gitlab.io or the link shown on your project Settings -> Pages.

Installation

  1. Having Hexo means you can debug locally, rather than waiting for CI. You can even run a local server to preview your blog (see step 6 below).
  2. Clone your repo to your workstation.
  3. Install Node.js 10 (current active LTS). Other distro, see this guide or here.
# Ubuntu 16.04 or newer
$ sudo snap install node --classic --channel=10
# Debian
$ curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
$ sudo apt-get install -y nodejs
# Fedora 29 or newer
$ sudo dnf install npm
# Fedora 28 or older
$ curl --silent --location https://rpm.nodesource.com/setup_10.x | sudo bash -
$ sudo yum -y install nodejs
# Arch Linux
$ sudo pacman -S npm
  1. Install Hexo and its dependencies (defined in package.json). Re-launch the terminal program before continue. After installation, append node_modules/.bin to $PATH (skip the echo step if you've already {% post_link running-locally-installed-node-packages 'done so' %}).
$ cd <folder>
$ npm install --only=prod
$ echo 'PATH="$PATH:./node_modules/.bin"' >> ~/.profile
  1. Generate static files to check for any error. You should always do this before pushing/merging commits to the master branch.
$ hexo generate
  1. (Optional) Start Hexo server on http://localhost:4000 to preview the blog.
$ hexo server

More info: Server

  1. Commit the changes and push them. The generated public and node_modules are ignored, as CI will generate them during build.
    1. I have migrated to Netlify and removed my GitLab page.
    2. Since I don't have a gitlab page any more, I removed the deploy command in the .gitlab-ci.yml.
    3. The config now has two parts. To use in gitlab page, simply uncomment the second part and comment out the first part.
    4. Make sure you {% post_link validity-gitlab-ci-config 'double-check' %} the CI config before you push.
  2. Check the build status by going to your project CI /CD -> Pipelines. Due to the limitation of hexo, the build will always pass even when there is error. Check the Jobs log, look for any error after $ hexo deploy.
  3. If there is no error, the generated website can be accessed on <your-username>.gitlab.io/ or the link shown on your project Settings -> Pages.

Writing

  1. Create a new post (using Hexo)
$ hexo new "My New Post"
  1. My-New-Post.md is created to the source/_posts folder, with the following header/front-matter:
---
title: My New Post
date: yyyy-mm-dd hh:mm:ss
tags:
categories:
---
  1. Write your post after the second --- using Markdown style.

More info: Writing

Configuration

Naming

Change the website's author and name _config.yml:

title:
subtitle:
description:
author:

themes/typing/_config.yml:

menu:
  GitLab: <your-gitlab-project-link>
# Customize /about page
nickname: 
description:

Favicon

RealFaviconGenerator provides a web-based tool to generate favicons with wide compatibility.

  1. Upload your favicon (at least 260x260) and configure however you want.
  2. Install the generated package to themes/typing/source folder. Make you replace all existing files.
  3. Edit themes/typing/layout/_partial/head.ejs. Change the color values of mask-icon and msapplication-TileColor to the values you configured on the generator.
  4. Check for any error using hexo generate (you should do this before you push any commit).
  5. Commit and push.
  6. Check your favicon with the favicon checker.

Project page

If you prefer to have a project page on GitLab:

  1. Go to Settings -> General -> Advanced -> Rename repository. Change the Path to a name, so the website is available at username.gitlab.io/name. It can be any name, like blog or hexo.
  2. Edit _config.yml, change the root: value from "" to "name".
  3. Commit and push.

Remove fork relationship

If you don't have any plan to send merge requests to the upstream, you can remove fork relationship permanently by going to Settings -> General -> Advanced -> Remove fork relationship.

Useful links:

Configuration files for this blog deployment:

Docs: