preface

Trying to set up a personal blog on Github, I found a lot of articles on the Internet, but some of them used old versions, some of the language is not clear, and finally stumbled together, so I wrote this article to summarize the pit I stepped in. The level is limited, please forgive me.

Blog address: Portal

System environment

  • Windows 10 Education
  • Node. Js v8.7.0
  • Npm v5.4.2
  • Git v2.13.0

Create the GitHub Pages project on GitHub

1. Create a warehouse

Github Pages fall into two categories, user or organization Pages and project Pages.

  • To create a user or organization home page, simply create a page named{yourusername}.github.ioA new warehouse will be fine. Side of theyourusernameEnter your own user name. Github recognizes and automatically sets the repository to Github Pages. The user’s home page is unique and any other name will be treated as a normal item.
  • Create the project home page. First build a new warehouse, name, or use the original warehouse can be. inProject home -> Settings -> Options -> Github PagesSet the Source option to Master Branch, then Save, and the project becomes a Github Pages project.

2. Branch management

Github Pages automatically deploys static web files, whereas the previous step was to make the Master branch the default branch for deployment.

Github Pages deployment branch Settings, there are three possible Settings:

  • The master branch
  • /doc folder under the master branch
  • Gh – pages branch

The gh-Pages branch option is displayed only when the branch is created.

Personally, I set up branches like this: create a new blog-src branch to manage Hexo source code, a gh-Pages branch to manage static web files generated by Hexo, which are deployed on Github Pages, and keep the Master branch (personal habit). You can also start a separate project to manage versions of the Hexo source code.

Install Hexo

To clarify the following code examples, <> is a mandatory parameter and [] is an optional parameter.

1. Install Hexo

npm install -g hexo-cli
Copy the code

2. Generate the Hexo project

Initialize Hexo in the folder where you want to create the blog.

hexo init [projectname]
Copy the code

If you have a project name, a folder with that name is generated; If there are no parameters, you must run in an empty folder, or an error will be reported.

3. Pull the Github project locally

git clone https://github.com/yourusername/yourprojectname.git
Copy the code

Then copy the contents of the previously generated Hexo project folder. Use Git by yourself, because Git code is easy to cause all kinds of errors. Finally, push the project onto the blog-src branch (with your own source branch).

Using Hexo

1. Common commands

  • hexo generate [-d]
  • hexo serve [-p port]
  • hexo deploy [-g]

Most of the Hexo commands can be abbreviated, for example, Hexo Serve — Port 5000 can be abbreviated to Hexo S -P 5000.

For more commands and parameters, see the official documentation.

2. Compile

[Optional] Clear cache:

hexo clean
Copy the code

Compile:

hexo g
Copy the code

3. Run

Enable service:

hexo s
Copy the code

The default startup address is http://localhost:4000/

If port 4000 is occupied:

hexo s -p [port]
Copy the code

Deployment of 4.

In the blog folder:

npm install hexo-deployer-git --save
Copy the code

This is using NPM to install hexo’s plug-in deployed to Git. — Save will write the package to package.json, so you don’t need to reinstall it when switching to another computer.

Modify the_config.yml:

deploy:
  type: git
  repo: [email protected]:yourusername/yourprojectname.git
  branch: gh-pages
Copy the code

Replace repO and Branch with your own.

Note:

1. Clone with SSH is available on Github. If you use Git, an error will be reported

2. Branch Select the branch set on Github Pages instead of pulling the branch from the project

Blog writing

The project structure

. ├ ─ ─. Deploy ├ ─ ─ public ├ ─ ─ scaffolds | ├ ─ ─ draft. The md | ├ ─ ─ page. The md | └ ─ ─ post. The md ├ ─ ─ scripts ├ ─ ─ source | ├ ─ ─ _drafts | └ ─ ─ _posts ├ ─ ─ themes ├ ─ ─ _config. Yml └ ─ ─ package. The jsonCopy the code

Scaffolds: Scaffolds are the header templates that the corresponding Layout uses to generate new blog posts

Source: The source file, the blog post will be layered according to layout

About add the template and draft see writing | Hexo.

The new post

hexo n [layout] <filename>
Copy the code

Header information

Post template MD:

---
title: {{ title }}
date: {{ date }}
tags:
---
Copy the code

Actual generated MD:

-- RocketMQ Installation and deploymentCopy the code

The time format is set in _config.yml, and Hexo will parse the blog post based on the time.

Replace the topic

Hexo bring is the default Theme of landscape, but we can from the Theme | Hexo or found on making love Theme.

Three ways to change themes

  • Download the Release package from the Github home page and unzip it tothemes/folder
$ git clonehttps://github.com/theme-next/hexo-theme-next - branch v6.0.0 themes/nextCopy the code
  • (Linux only)
$ mkdir themes/next
$ curl -s https://api.github.com/repos/theme-next/hexo-theme-next/releases/latest | grep tarball_url | cut -d '"' -f 4 | wget -i - -O- | tar -zx -C themes/next --strip-components=1
Copy the code

Set the theme

In the _config.yml of the project, change theme: to the name of the folder under Themes /. If it’s hexo-theme-next-6.1.0, write hexo-theme-next-6.1.0. If it’s self-built next, write next.

Change the Next theme

Next is one of Hexo’s most popular themes, but when I used it, I found that the documentation for V6.0.0 on Github’s home page was not extensive, and the official website was not yet available. The old documentation could be used for reference, but there were some minor differences. The new version is distinguished below by V5 and V6.

Document address for V5

Old home page (updated to V5.1.2) : github.com/iissnan/hex…

New home page (updated here after V6.0.0) : github.com/theme-next/…

Configuring the Next Theme

Next version: V6.1.0

Modify _config.yml for the topic (note the distinction between project and topic). The entire file is a thousand lines long, with a lot of configuration items and a lot of comments. I’ve just picked a few of them and you can change them as you want.

Switch style

Officials offer four styles, each with its own strengths.

# -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
# Scheme Settings
# -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --

# Schemes
#scheme: Muse
#scheme: Mist
#scheme: Pisces
scheme: Gemini
Copy the code

Language selection

Modify the Language option in _config.yml of the project:

Writing # 1
language: zh-CN
# 2, you can use the top language
language:
- zh-CN
- _en
Copy the code

Different from V5, simplified Chinese is zh-CN and English is _en. The language file is located under the language/ folder of the topic. The name of the corresponding YML file is the name of the language. You can modify the corresponding language file to modify the expression of some specified fields, or customize the fields of the corresponding language. You can refer to international | Hexo.

Social networking pages

Uncomment and modify as needed. The icons_only below is’ show icon only ‘, I think it is more concise to change to true.

# Social Links.
# Usage: `Key: permalink || icon`
# Key is the link label showing to end users.
# Value before `||` delimeter is the target permalink.
# Value after `||` delimeter is the name of FontAwesome icon. If icon (with or without delimeter) is not specified, globe icon will be loaded.
social:
  GitHub: https://github.com/yourname || github
  E-Mail: [email protected] || envelope
  #Google: https://plus.google.com/yourname || google
  #Twitter: https://twitter.com/yourname || twitter
  #FB Page: https://www.facebook.com/yourname || facebook
  #VK Group: https://vk.com/yourname || vk
  #StackOverflow: https://stackoverflow.com/yourname || stack-overflow
  #YouTube: https://youtube.com/yourname || youtube
  #Instagram: https://instagram.com/yourname || instagram
  #Skype: skype:yourname? call|chat || skype

social_icons:
  enable: true
  icons_only: true
  transition: false
  # Dependencies: exturl: true in Tags Settings section below.
  # To encrypt links above use https://www.base64encode.org
  # Example encoded link: `GitHub: aHR0cHM6Ly9naXRodWIuY29tL3RoZW1lLW5leHQ= || github`
  exturl: false

# Follow me on GitHub banner in right-top corner.
# Usage: `permalink || title`
# Value before `||` delimeter is the target permalink.
# Value after `||` delimeter is the title and aria-label name.
#github_banner: https://github.com/yourname || Follow me on GitHub
Copy the code

Q&A

1. Github sent email – compilation failed

The page build failed for the master branch with the following error:

The tag fancybox on line 77 in themes/landscape/README.md is not a recognized Liquid tag.

  • See changes _config. Yml
  • Select the Github Pages branch
  • Do not use Git to push directly_config.ymlTo set the deploy configuration, and then usehexo d -gCommand push

2. hexo d -gfailure

error: failed to execute prompt script (exit code 1)
fatal: could not read Username for 'https://github.com': No error
FATAL Something's wrong. Maybe you can find the solution here: http://hexo.io/docs/troubleshooting.html
Copy the code
  • See changes _config. Yml
  • Change the HTTPS protocol to Gitgithub.comAfter that, HTTPS is/, Git is: