BUILD Personal Website with Hexo and GitHub Pages

<div style="text-align:center"><img src="https://hackmd.io/_uploads/r1__F07z1x.png" /></div> <p style="text-align: center"><b><font size=5 color=blueyellow>BUILD Personal Website with Hexo and GitHub Pages</font></b></p> **Contents of this documents and quicklinks**： [TOC] ## 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](https://nodejs.org/en) 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](https://cloud.tencent.com/developer/article/1938607) - Download and install the binary file, you need to configure the bash environment, see the [reference](https://cloud.tencent.com/developer/article/1772306) After the installation is complete, enter the following commands in the terminal: ```javascript= $ 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](https://coderefinery.org/) - [Introduction to version control with Git](https://coderefinery.github.io/git-intro/) - [Collaborative distributed version control](https://coderefinery.github.io/git-collaborative/) Following the instructions [HERE](https://github.com/git-guides/install-git) 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](https://hexo.io/docs/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](https://ejs.co/), [Stylus](https://stylus-lang.com/) and [Markdown](https://daringfireball.net/projects/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-s](https://hackmd.io/_uploads/rJFcekNMke.jpg) - `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](https://hexo.io/themes/) and select one to make your website attractive and professional. Personally, I like [Fluid](https://github.com/fluid-dev/hexo-theme-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. ![hexo-fluid-theme](https://hackmd.io/_uploads/ryeqh-pRbJg.jpg) For more configuration, please refer to [Hexo Fluid Docs](https://hexo.fluid-dev.com/docs/en/start/). --- ## 4. Personalize domain [GitHub Pages](https://docs.github.com/en/pages/getting-started-with-github-pages/about-github-pages#about-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](https://pages.github.com/) 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` - ![github-new-repository](https://hackmd.io/_uploads/H1zcoAmfye.jpg) - 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. - ![github-repo-name](https://hackmd.io/_uploads/SJ49Yk4zJe.jpg) - 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. ```bash= 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`. - ![github-global-setting](https://hackmd.io/_uploads/H1WLnCXGJl.jpg) - In the `Access` section of the sidebar, click `SSH and GPG keys`. - ![github-ssh-key](https://hackmd.io/_uploads/H1fYhAmfke.jpg) - Click the green button with the name of `New SSH key` or `Add SSH key` - ![github-new-ssh](https://hackmd.io/_uploads/BJt0FyNG1l.jpg) - 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-add-ssh-key](https://hackmd.io/_uploads/HJKJ5kEzJg.jpg) - 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 git@github.com` - 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)](https://docs.github.com/en/authentication/troubleshooting-ssh/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. ```yaml= # 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](https://docs.github.com/en/pages/configuring-a-custom-domain-for-your-github-pages-site) and add it to GitHub Pages ![github-depolyment](https://hackmd.io/_uploads/HJA_kk4fyx.jpg) ### 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](https://www.markdownguide.org/basic-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. ![new-hello-world](https://hackmd.io/_uploads/HyB7eJNGkl.jpg) --- ## 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. :::danger :::