From 20632c9c26678e61f4565e3c438d416726f7a0be Mon Sep 17 00:00:00 2001 From: curben Date: Fri, 21 Sep 2018 14:09:51 +0930 Subject: [PATCH] Create installation guide post Move the lengthy installation guide to a new blog post. --- README.md | 82 ++++++++++++++---------- source/_posts/How-to-hexo.md | 117 +++++++++++++++++++++++++++++++++++ source/_posts/Test-page.md | 6 -- source/_posts/hello-world.md | 38 ------------ 4 files changed, 165 insertions(+), 78 deletions(-) create mode 100644 source/_posts/How-to-hexo.md delete mode 100644 source/_posts/Test-page.md delete mode 100644 source/_posts/hello-world.md diff --git a/README.md b/README.md index 60d8621..9c04efe 100644 --- a/README.md +++ b/README.md @@ -2,19 +2,23 @@ curben.gitlab.io ================ ![Build Status](https://gitlab.com/curben/curben.gitlab.io/badges/master/pipeline.svg) +![https://www.npmjs.com/package/hexo](https://img.shields.io/badge/hexo-3.7.1-blue.svg) Forked from GitLab's [Hexo](https://gitlab.com/pages/hexo) example with [Typing](https://github.com/geekplux/hexo-theme-typing) theme. -## Installation (GitLab Pages only) -1. Fork this project. -1. Make sure Shared Runners is enabled. Go to your (forked) project `Settings -> CI / CD -> Shared Runners`. -1. Change project website to a user website, so the website's home page is available at `.gitlab.io/`, instead of `.gitlab.io/hexo`. - Go to `Settings -> General -> Advanced -> Rename repository`. Change the Path to `.gitlab.io`. -1. Clone this project to your workstation. Change `` to a preferred name. +--- + +{:toc} + +--- + +## Installation + +1. Change `` to a preferred name. ```bash git clone https://gitlab.com/curben/curben.gitlab.io ``` -1. Install Node.js. +2. Install Node.js. ```bash # Installing npm will also install nodejs as dependency. # Ubuntu/Debian @@ -24,44 +28,54 @@ sudo yum install npm # Arch Linux sudo pacman -S npm ``` -1. Install Hexo and its dependencies (defined in [package.json](package.json)). +3. Install Hexo and its dependencies (defined in [package.json](package.json)). ```bash -sudo npm install -g hexo-cli -cd -npm install +$ sudo npm install -g hexo-cli +$ cd +$ npm install ``` -1. Edit [README.md](README.md) and make whatever changes, can be just a word. -1. Generate static files to check for any error. You should always do this before pushing/merging commits to the `master` branch. +4. Generate static files to check for any error. You should _always_ do this before pushing/merging commits to the `master` branch. ```bash -hexo generate +$ hexo generate ``` -1. Commit the changes and push them. The generated `public` and `node_modules` are [ignored](.gitnore), as GitLab runner will generate itself. -1. 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 error occurred. Check the Jobs log, look for any error in `$ hexo deploy`. -1. If no error, the generated website would be available on `.gitlab.io/` or the link shown on your project `Settings -> Pages`. -1. Follow this [guide](https://hexo.io/docs/writing) to create a new post or a new page. -## Configuration +## Quick Start -### Favicon (recommended) -[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. Install the generated package to [favicons](themes/typing/source/favicons/) folder. -1. Edit [head.ejs](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. Check for any error using `hexo generate` (you should do this *before* you push any commit). -1. Commit and push. -1. Check your favicon with the [favicon checker](https://realfavicongenerator.net/favicon_checker). +### Create a new post -### Project page (optional) -If you prefer to have a project page on GitLab -1. go to `Settings -> General -> Advanced -> Rename repository`. Change the Path to ``, so the website is available at `.gitlab.io/`, `` can be any name, like `blog` or `hexo`. -1. Edit [_config.yml](_config.yml), change the `root:` value from `""` to `"/ General -> Advanced -> Remove fork relationship`. +More info: [Writing](https://hexo.io/docs/writing.html) + +### Run server + +``` bash +$ hexo server +``` + +More info: [Server](https://hexo.io/docs/server.html) + +### Generate static files + +``` bash +$ hexo generate +``` + +More info: [Generating](https://hexo.io/docs/generating.html) + +### Deploy to remote sites + +``` bash +$ hexo deploy +``` + +More info: [Deployment](https://hexo.io/docs/deployment.html) ## Changes The following are the major changes I made from the upstream. + ### Hexo - Update [.gitlab-ci.yml](.gitlab-ci.yml) to use the latest version of [Node.js](https://hub.docker.com/_/node/) in the Docker image. - Update [package.json](package.json) to use latest version of [hexo](https://www.npmjs.com/package/hexo) and its related packages. diff --git a/source/_posts/How-to-hexo.md b/source/_posts/How-to-hexo.md new file mode 100644 index 0000000..0d8d6ea --- /dev/null +++ b/source/_posts/How-to-hexo.md @@ -0,0 +1,117 @@ +--- +title: Create a Hexo blog using GitLab Pages +date: 2018-09-21 00:00:00 +tags: +--- +Create a website/blog (hosted by [GitLab](https://about.gitlab.com/features/pages/) for free) using the following guide: + +## Create a new GitLab project +1. Register a free [GitLab](https://gitlab.com/users/sign_in#register-pane) account or use your current one. +2. Fork this project. +3. Ensure Shared Runners is 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 `.gitlab.io/`, instead of `.gitlab.io/hexo`. + Go to `Settings -> General -> Advanced -> Rename repository`. Change the Path to `.gitlab.io`. +5. If you just want to use a similar layout as this blog, or you're not planning to customize it, you don't have to [install](#installation) Hexo. You still need to change the blog's name and favicon though ([how-to](#naming). + Having Hexo makes it easier for you to debug, rather than relying entirely on the GitLab runner. + 1. To create a new post (*without* using [Hexo](https://hexo.io/docs/writing)), create a new `.md` in the [source/_posts](source/_posts) folder. + 2. Start with the following header/[front-matter](https://hexo.io/docs/front-matter): + ``` + --- + title: Test page + date: yyyy-mm-dd hh:mm:ss + tags: + 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). +6. After you create a new post, the website would be available on `.gitlab.io/` or the link shown on your project `Settings -> Pages`. + +## Installation +1. Clone this project to your workstation. Change `` to a preferred name. +```bash +$ git clone https://gitlab.com/curben/curben.gitlab.io +``` +2. Install Node.js. +```bash +# Installing npm will also install nodejs as dependency. +# Ubuntu/Debian +$ sudo apt-get install npm +# Fedora/Red Hat +$ sudo yum install npm +# Arch Linux +$ sudo pacman -S npm +``` +3. Install Hexo and its dependencies (defined in [package.json](package.json)). +```bash +$ sudo npm install -g hexo-cli +$ cd +$ npm install +``` +4. Generate static files to check for any error. You should always do this before pushing/merging commits to the `master` branch. +```bash +$ hexo generate +``` +5. Commit the changes and push them. The generated `public` and `node_modules` are [ignored](.gitnore), as GitLab runner will generate them by itself. +6. 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 error occurred. Check the Jobs log, look for any error in `$ hexo deploy`. +7. If there is no error, the generated website would be available on `.gitlab.io/` or the link shown on your project `Settings -> Pages`. + +## Writing +1. Create a new post (using Hexo) +``` bash +$ hexo new "My New Post" +``` +2. `My-New-Post.md` is saved to the [source/_posts](source/_posts) folder, with the following header/[front-matter](https://hexo.io/docs/front-matter): +``` +--- +title: My New Post +date: yyyy-mm-dd hh:mm:ss +tags: +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). + +To create a new page or more info: [Writing](https://hexo.io/docs/writing.html) + +## Configuration +### Naming +Change the website's author and name +[_config.yml](_config.yml): +```yml +title: +subtitle: +description: +author: +``` +[themes/typing/_config.yml](themes/typing/_config.yml): +```yml +menu: + GitLab: +# Customize /about page +nickname: +description: +``` + +### Favicon +[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. Install the generated package to [favicons](themes/typing/source/favicons/) folder. +1. Edit [head.ejs](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. Check for any error using `hexo generate` (you should do this *before* you push any commit). +1. Commit and push. +1. Check your favicon with the [favicon checker](https://realfavicongenerator.net/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 ``, so the website is available at `.gitlab.io/`, `` can be any name, like `blog` or `hexo`. +1. Edit [_config.yml](_config.yml), change the `root:` value from `""` to `"/ General -> Advanced -> Remove fork relationship`. + +## Useful links: +[Hexo Docs](https://hexo.io/docs/) +[GitLab Pages](https://docs.gitlab.com/ee/user/project/pages/index.html) + + diff --git a/source/_posts/Test-page.md b/source/_posts/Test-page.md deleted file mode 100644 index 20dedd4..0000000 --- a/source/_posts/Test-page.md +++ /dev/null @@ -1,6 +0,0 @@ ---- -title: Test page -date: 2018-09-19 12:45:28 -tags: ---- -This a test page. diff --git a/source/_posts/hello-world.md b/source/_posts/hello-world.md deleted file mode 100644 index c090297..0000000 --- a/source/_posts/hello-world.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: Hello World ---- -Welcome to [Hexo](https://hexo.io/)! This is your very first post. Check [documentation](https://hexo.io/docs/) for more info. If you get any problems when using Hexo, you can find the answer in [troubleshooting](https://hexo.io/docs/troubleshooting.html) or you can ask me on [GitHub](https://github.com/hexojs/hexo/issues). - -## Quick Start - -### Create a new post - -``` bash -$ hexo new "My New Post" -``` - -More info: [Writing](https://hexo.io/docs/writing.html) - -### Run server - -``` bash -$ hexo server -``` - -More info: [Server](https://hexo.io/docs/server.html) - -### Generate static files - -``` bash -$ hexo generate -``` - -More info: [Generating](https://hexo.io/docs/generating.html) - -### Deploy to remote sites - -``` bash -$ hexo deploy -``` - -More info: [Deployment](https://hexo.io/docs/deployment.html)