BUILD Personal Website with Hexo and GitHub Pages

Contents of this documents and quicklinks：

• 1. Introduction
• 2. Environment setup
  • 2.1 Install Node.js locally
  • 2.2 Install Git
  • 2.3 Install Hexo
  • 2.4 Initialize Hexo
• 3. Customize Hexo theme
• 4. Personalize domain
  • 4.1 Create a GitHub Pages repository
  • 4.2 Generate a SSH key
  • 4.3 Add the SSH key to your Github account
  • 4.4 Update _config.yml in root dict
  • 4.5 Update GitHub repository
  • 4.6 Create a new post
• 5. Summary

1. Introduction

It has been a long time since I would like to own a particular space to record my work and enjoy my hobby of writting, and until now I've finally started creating my personal website here. Among a variety of schemes, I adopt Hexo + GitHub Pages, which is friendly to noob like me.

Hexo is a fast, simple & powerful blog framework. Simply write post in Markdown and Hexo generates static files deployed to GitHub Pages.

As the first post, I am writing this article just in case anyone who is also interested in having a personal website but hasn't been prepared yet. On the other hand, it will be an importent reference for myself to re-create the environment efficiently when I change the Mac or migrate data in the future.

2. Environment setup

2.1 Install Node.js locally

Node.js is a free, open-source, cross-platform (Mac OS, Window, Linux), and JavaScript runtime environment that lets developers create servers, web apps, command line tools and scripts.

Navigate to Node.js webpage and select the appropriate installation file to download according to your local environment.

• For Windows and Mac OS users, click the installer file to install it.
• For Linux users, the installation is somewhat complicated. The following two installation methods are recommended, and you can choose one of them:
  • Compile and install from source code without configuring bash, but compiling takes time, see the reference
  • Download and install the binary file, you need to configure the bash environment, see the reference

After the installation is complete, enter the following commands in the terminal:

$ npm -v
$ node -v

If there are output with version numbers, the installation of Node.js is successful in your local computer.

2.2 Install Git

Git is a distributed version control system that tracks versions of files. It is often used to control source code by programmers who are developing software collaboratively.

If you are not familiar with Git, or you have heard of Git but want to know more about it, you can come to the lesson materials from CodeRefinery

• Introduction to version control with Git
• Collaborative distributed version control

Following the instructions HERE to install Git.

After the installation, right-click the mouse anywhere on your desktop or in a folder. If you see the following options:

• Open Git GUI here
• Open Git Bash here

then Git has been successfully installed on your computer.

2.3 Install Hexo

Hexo is a fast, simple, and powerful blogging framework powered by Node.js. It allows users to create static websites, blogs, or portfolios with minimal setup. Hexo uses Markdown files for content, which makes it easy to write posts, and it generates static HTML files, which makes it fast for hosting.

Moreover, Hexo provides many themes that you can easily integrate to your blog with a full of customization.

Once Node.js and Git are successfully installed, you can use npm (Node Package Manager) to install Hexo:

$ npm install -g hexo-cli
$ npm install hexo

2.4 Initialize Hexo

Once Hexo is installed, run the following commands to initialize Hexo in the target <my-website>.

$ hexo init <my-website>
$ cd <my-website>
$ npm install

This will creates a new directory (<my-website>) with the default/essential structure of a Hexo site and installs the required dependencies. Your project folder will look like:

.
├── _config.yml
├── package.json
├── scaffolds
├── source
|   ├── _drafts
|   └── _posts
└── themes

• The _config.yml is the "site config" file in Hexo root dict, personalize the top contents like title, subtitle, author, description and other global settings.
• The package.json file contains the application data. The EJS, Stylus and Markdown renderers are installed by default.
• Scaffold folder: When you create a new post, Hexo bases the new file on the scaffold.
• Source folder: This is where you put your site’s content. Hexo ignores hidden files and files or folders whose names are prefixed with _ (underscore) - except the _posts folder. Renderable files (e.g. Markdown, HTML) will be processed and put into the public folder, while other files will simply be copied.
• Theme folder: Hexo generates a static website by combining the site contents with the theme.

Run the following basic commands to compile Hexo

• hexo clean to clear the static files and cache
• hexo g to generate static web files locally
• hexo s to start a local sever for preview
  • Hexo will be run at localhost:4000 by default. Now open http://localhost:4000 in your browser to see the result.
• hexo d to deploy after generation finish (will talk this part in the following section)

---

3. Customize Hexo theme

The Hexo community provides a lot of themes that you can choose to personalize your website. Navigate to the Hexo themes and select one to make your website attractive and professional.

Personally, I like Fluid, an elegant Material-Design theme, particularly for writing posts. If you prefer the other themes, the configuration method should be similar.

• Download Fluid theme and then the _config.fluid.yml file in root dict is created for custom.

npm install --save hexo-theme-fluid

• Modify _config.yml in root dict via replacing the theme config with your new theme name.

# Extensions
theme: fluid

Run the command hexo s again and open the http://localhost:4000 in your browser to see the result using the Fluid theme.

For more configuration, please refer to Hexo Fluid Docs.

---

4. Personalize domain

GitHub Pages is a static site hosting service that takes HTML, CSS, and JavaScript files straight from a repository on GitHub, optionally runs the files through a build process, and publishes a website.

To publish a user site, we can follow the getting started instructions to set up your site using GitHub Pages.

4.1 Create a GitHub Pages repository

We should create a repository on GitHub.

• In the upper-right corner of any page of your Github account, select +, then click New repository
• Enter <username>.github.io as the repository name. For example, if your username is octocat, the repository name should be octocat.github.io. This link will end up being the base URL of your website.
• Choose a repository visibility (Public or Private).
• Select Initialize this repository with a README.
• Click Create repository.

4.2 Generate a SSH key

You can generate a new SSH key on your local machine. After you generate the key, you can add the public key to your account on GitHub.com to enable authentication for Git operations over SSH.

• Open Git Bash.
• Paste the text below, replacing <your_email> with your GitHub email address.
  ​​​​ssh-keygen -t ed25519 -C "<your_email>"
  

  • When you're prompted to "Enter file in which to save the key (/c/Users/XXX/.ssh/id_ed25519):", you can press Enter to accept the default file location.
  • Please note that if you created SSH keys previously, ssh-keygen may ask you to rewrite another key, in which case we recommend creating a custom-named SSH key.
• Type a secure passphrase when you see the following output at the prompt:
  ​​​​> Enter passphrase (empty for no passphrase): [Type a passphrase]
  ​​​​> Enter same passphrase again: [Type passphrase again]
  

4.3 Add the SSH key to your Github account

You can add the generated SSH key and use it for authentication, or commit signing, or both.

• Copy the SSH public key to your clipboard.
• In the upper-right corner of any page on GitHub, click your profile photo, then click Settings.
  • 
• In the Access section of the sidebar, click SSH and GPG keys.
  • 
• Click the green button with the name of New SSH key or Add SSH key
  • 
• In the "Title" field, add a descriptive label for the ssh key.
• Select the type of key, either Authentication Key or Signing Key.
• Paste your public key in the "Key" field.
• Click Add SSH key.
  • 
• GitHub will prompt you to enter your password for confirmation.
• Test your SSH connection via Git Bash prompt (windows users) and terminal (Mac OS and Linux users)
  • Enter the command ssh -T [e-mail]
  • You may see a warning like this:
  ​​​​> The authenticity of host 'github.com (IP ADDRESS)' can't be established.
  ​​​​> ED25519 key fingerprint is SHA256:+(XXXXX).
  ​​​​> Are you sure you want to continue connecting (yes/no)?
  

  • Verify the fingerprint in this message matches GitHub's public key fingerprint. If it does, then type yes and you will theoretically get
  ​​​​> Hi USERNAME! You've successfully authenticated.
  

  • If you receive a "permission denied" message, you can come to the Error: Permission denied (publickey) webpage to see how to solve this problem.

4.4 Update _config.yml in root dict

As we have adopted the Fluid theme in the _config.yml file, we scroll down to the bottom of this file and update it with your depolyment target information.

# Deployment
deploy:
  type: git
  repository: https://github.com/<username>/<username>.github.io
  branch: main

At the root dict, right-click the mouse and click Open Git Bash Here and then run the following basic commands

• hexo clean to clear the static files and cache
• hexo g && hexo s to generate static web files locally and then to start a local sever at http://localhost:4000/ for preview
• hexo d to deploy once you can make sure that all the info at http://localhost:4000/ are correct
  • your depolyment will be successful if you see the output INFO Deploy done: git
  • If there is an error info like ERROR Deployer not found: git, run the command npm install hexo-deployer-git --save and regenerate and redepoly your materials via
    ​​​​​​​​hexo clean && hexo generate
    ​​​​​​​​hexo deploy
    

4.5 Update GitHub repository

• Come to the Github repository for your personal website, which should be https://github.com/<username>/<username>.github.io, and then the Settings at upper part of your web brower.
• In the Code and automation section of the sidebar, click Pages.
  • In the Build and deployment/Source section, you should choose Deploy from a branch
  • Select main/(root) at the Branch section and save it
• Wait for several minutes and you will see the URL for your personal website.
  • if you have your own custom domain, you can follow the instructions HERE and add it to GitHub Pages

4.6 Create a new post

At the root dict of Hexo project (<my-website>), right-click the mouse and click Open Git Bash Here

• run the command hexo new "NEW hello world" and it will create a new file (NEW-hello-world.md) in <PATH>/source/_posts/> with some default front-matter.
• Edit this file and add content to your post with basic Markdown Syntax.
• run the Hexo commands mentioned above to generate static HTML files and then depoly these new files to Github Page.

After deployment, visit https://<username>.github.io to see your live site.

---

5. Summary

Using GitHub Pages to build a personal website and distinguish yourself with a recognizable identity and external brand in your communities of interest is a worthwhile endeavor if you’re willing to spend some extra time setting things up. Hexo and Github Page become such a great tool for you. This pairing is a convenient, performant and free blogging platform. With its simplicity and its community, it’s easy to set up, allowing you to just focus on what matters: Your sharing. I hope you find this post useful.