curben
/
blog
mirror of https://gitlab.com/curben/blog
1
0
Fork 0
Code Issues Releases Wiki Activity

style: more consistent formatting

This commit is contained in:
curben 2018-11-10 20:32:49 +10:30
parent ade47b60ad
commit 30f78af374
1 changed files with 44 additions and 21 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

65
source/_posts/how-to-create-a-hexo-blog.md
View File

@ -1,20 +1,23 @@
--- ---
title: How to create a Hexo blog title: How to create a Hexo blog on GitLab Pages
date: 2018-09-21 00:00:00 date: 2018-09-21 00:00:00
lastUpdated: 2018-11-06 00:00:00 lastUpdated: 2018-11-10 00:00:00
tags: tags:
--- ---
Create a website/blog (hosted by [GitLab](https://about.gitlab.com/features/pages/) for free) using the following guide: Create a website/blog using Hexo on [GitLab Pages](https://about.gitlab.com/features/pages/) for free using the following guide. Refer to my {% post_link hexo-blog-github 'another guide' %} for [GitHub Pages](https://pages.github.com/).
<!-- more --> <!-- more -->
## GitLab project ## GitLab project
1. Register a free [GitLab](https://gitlab.com/users/sign_in#register-pane) account or use your current one. 1. Register a free [GitLab](https://gitlab.com/users/sign_in#register-pane) account or use your current one.
2. Fork this project. 2. Fork the [repo of this blog](https://gitlab.com/curben/blog).
3. Shared Runners should be enabled. Go to your (forked) project `Settings -> CI / CD -> Shared Runners`. 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 `<your-username>.gitlab.io/`, instead of `<your-username>.gitlab.io/hexo`. 4. Change project website to a user website. This is so that the website's home page is <b>*username*.gitlab.io</b>, instead of username.gitlab.io/hexo.
Go to `Settings -> General -> Advanced -> Rename repository`. Change the Path to `<your-username>.gitlab.io`. Go to `Settings -> General -> Advanced -> Rename repository`. Change the Path to <b>*username*.gitlab.io</b>, where username is your username on GitLab.
5. You can start writing a new post straightaway without [installing](#installation) Hexo. You still need to change the blog's name and favicon though ([how-to](#naming)). 5. You can start writing a new post straight away without [installing](#installation) Hexo. You still need to change the blog's name and favicon though ([how-to](#naming)).
1. To create a new post (through GitLab.com), create a new `<post-title>.md` file in `source/_posts` folder. 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](https://hexo.io/docs/front-matter): 2. Start with the following header/[front-matter](https://hexo.io/docs/front-matter):
``` ```
--- ---
title: Test page title: Test page
@ -23,16 +26,16 @@ Create a website/blog (hosted by [GitLab](https://about.gitlab.com/features/page
categories: categories:
--- ---
``` ```
3. Write your post after the second `---` using [Markdown](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) [style](https://docs.gitlab.com/ee/user/markdown.html). 3. Write your post after the second `---` using [Markdown](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) [style](https://docs.gitlab.com/ee/user/markdown.html).
6. After you create a new post, the website can be accessed on `<your-username>.gitlab.io/` or the link shown on your project `Settings -> Pages`.
6. After you create a new post, the website can be accessed on <b>*username*.gitlab.io</b> or the link shown on your project `Settings -> Pages`.
## Installation ## Installation
1. Having Hexo means you can debug locally, rather than waiting for [CI](https://docs.gitlab.com/ee/ci/). You can even run a local server to preview your blog (see step 6 below). 1. Having Hexo means you can debug locally, rather than waiting for [CI](https://docs.gitlab.com/ee/ci/). You can even run a local server to preview your blog (see step 6 below).
2. Clone this project to your workstation. Change `<folder>` to a preferred name. 2. Clone your repo to your workstation.
```bash
$ git clone https://gitlab.com/curben/blog <folder>
```
3. Install Node.js 10. Other distro, see this [guide](https://nodejs.org/en/download/package-manager/) or [here](https://github.com/nodesource/distributions). 3. Install Node.js 10. Other distro, see this [guide](https://nodejs.org/en/download/package-manager/) or [here](https://github.com/nodesource/distributions).
```bash ```bash
# Installing npm will also install nodejs as dependency. # Installing npm will also install nodejs as dependency.
# Ubuntu 16.04 or newer # Ubuntu 16.04 or newer
@ -48,34 +51,45 @@ $ sudo yum -y install nodejs
# Arch Linux # Arch Linux
$ sudo pacman -S npm $ sudo pacman -S npm
``` ```
4. Install Hexo and its dependencies (defined in `package.json`). Re-launch the terminal program before continue. After installation, append `node_modules/.bin` to $PATH.
4. 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' %}).
```bash ```bash
$ cd <folder> $ cd <folder>
$ npm install $ npm install
$ echo 'PATH="$PATH:./node_modules/.bin"' >> ~/.profile $ echo 'PATH="$PATH:./node_modules/.bin"' >> ~/.profile
``` ```
5. Generate static files to check for any error. You should always do this before pushing/merging commits to the `master` branch. 5. Generate static files to check for any error. You should always do this before pushing/merging commits to the `master` branch.
```bash ```bash
$ hexo generate $ hexo generate
``` ```
6. (Optional) Start Hexo server on localhost:4000 to preview the blog. ([more info](https://hexo.io/docs/server))
6. (Optional) Start Hexo server on `http://localhost:4000` to preview the blog.
```bash ```bash
$ hexo server $ hexo server
``` ```
More info: [Server](https://hexo.io/docs/server)
7. Commit the changes and push them. The generated `public` and `node_modules` are [ignored](https://gitlab.com/curben/blog/blob/master/.gitignore), as CI will generate them during build. 7. Commit the changes and push them. The generated `public` and `node_modules` are [ignored](https://gitlab.com/curben/blog/blob/master/.gitignore), as CI will generate them during build.
1. I have migrated to [Netlify](https://www.netlify.com/) and removed my GitLab page. 1. I have migrated to [Netlify](https://www.netlify.com/) and removed my GitLab page.
2. Since I don't have a gitlab page anymore, I removed the deploy command in the `.gitlab-ci.yml`. 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. 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 double-check the CI config before you push. 4. Make sure you {% post_link validity-gitlab-ci-config 'double-check' %} the CI config before you push.
8. 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`. 8. 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`.
9. 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`. 9. 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 ## Writing
1. Create a new post (using Hexo) 1. Create a new post (using Hexo)
``` bash ``` bash
$ hexo new "My New Post" $ hexo new "My New Post"
``` ```
2. `My-New-Post.md` is created to the `source/_posts` folder, with the following header/[front-matter](https://hexo.io/docs/front-matter): 2. `My-New-Post.md` is created to the `source/_posts` folder, with the following header/[front-matter](https://hexo.io/docs/front-matter):
``` ```
--- ---
title: My New Post title: My New Post
@ -84,21 +98,25 @@ tags:
categories: categories:
--- ---
``` ```
4. Write your post after the second `---` using [Markdown](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) [style](https://docs.gitlab.com/ee/user/markdown.html). 4. Write your post after the second `---` using [Markdown](https://about.gitlab.com/handbook/product/technical-writing/markdown-guide/) [style](https://docs.gitlab.com/ee/user/markdown.html).
To create a new page or more info: [Writing](https://hexo.io/docs/writing.html) More info: [Writing](https://hexo.io/docs/writing.html)
## Configuration ## Configuration
### Naming ### Naming
Change the website's author and name Change the website's author and name
`_config.yml`: `_config.yml`:
```yml ```yml
title: title:
subtitle: subtitle:
description: description:
author: author:
``` ```
`themes/typing/_config.yml`: `themes/typing/_config.yml`:
```yml ```yml
menu: menu:
GitLab: <your-gitlab-project-link> GitLab: <your-gitlab-project-link>
@ -109,6 +127,7 @@ description:
### Favicon ### Favicon
[RealFaviconGenerator](https://realfavicongenerator.net/) provides a web-based tool to generate favicons with wide compatibility. [RealFaviconGenerator](https://realfavicongenerator.net/) provides a web-based tool to generate favicons with wide compatibility.
1. Upload your favicon (at least 260x260) and configure however you want. 1. Upload your favicon (at least 260x260) and configure however you want.
1. Install the generated package to `themes/typing/source` folder. Make you replace all existing files. 1. Install the generated package to `themes/typing/source` folder. Make you replace all existing files.
1. 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. 1. 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.
@ -118,8 +137,9 @@ description:
### Project page ### Project page
If you prefer to have a project page on GitLab: If you prefer to have a project page on GitLab:
1. go to `Settings -> General -> Advanced -> Rename repository`. Change the Path to `<directory>`, so the website is available at `<your-username>.gitlab.io/<directory>`, `<directory>` can be any name, like `blog` or `hexo`.
1. Edit `_config.yml`, change the `root:` value from `""` to `"/<directory>/"`. 1. Go to `Settings -> General -> Advanced -> Rename repository`. Change the Path to a name, so the website is available at <b>username.gitlab.io/*name*</b>. It can be any name, like *blog* or *hexo*.
1. Edit **_config.yml**, change the `root:` value from `""` to "*name*".
1. Commit and push. 1. Commit and push.
### Remove fork relationship ### Remove fork relationship
@ -127,10 +147,13 @@ If you don't have any plan to send merge requests to the upstream, you can remov
## Useful links: ## Useful links:
Configuration files for this blog deployment: Configuration files for this blog deployment:
- [.gitlab-ci.yml](https://gitlab.com/curben/blog/blob/master/.gitlab-ci.yml) - [.gitlab-ci.yml](https://gitlab.com/curben/blog/blob/master/.gitlab-ci.yml)
- [_config.yml](https://gitlab.com/curben/blog/blob/master/_config.yml) - [_config.yml](https://gitlab.com/curben/blog/blob/master/_config.yml)
- [package.json](https://gitlab.com/curben/blog/blob/master/package.json) - [package.json](https://gitlab.com/curben/blog/blob/master/package.json)
- [netlify.toml](https://gitlab.com/curben/blog/blob/master/netlify.toml) *for Netlify deployment only* - [netlify.toml](https://gitlab.com/curben/blog/blob/master/netlify.toml) *for Netlify deployment only*
[Hexo Docs](https://hexo.io/docs/) Docs:
[GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/index.html)
- [Hexo Docs](https://hexo.io/docs/)
- [GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/index.html)