Jay's Blog
0%

Posted on Edited on Disqus:

Overview

The blog I just built using Hexo is still pretty rough. There are lot features came with the next theme that can be enabled with one line of code to make this blog more robust. I will go over details about menu settings, social media link settings, footer settings, etc.

Basic configuration

Open _config.uml file under blog/themes/next/_config.yml. Uncomment the setting under menu section to enable features such as home, tags, about, etc.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
# Usage: `Key: /link/ || icon`
# Key is the name of menu item. If the translation for this item is available, the translated text will be loaded, otherwise the Key name will be used. Key is case-sensitive.
# Value before `||` delimiter is the target link, value after `||` delimiter is the name of Font Awesome icon.
# External url should start with http:// or https://
menu:
  home: / || fa fa-home
  about: /about/ || fa fa-user
  tags: /tags/ || fa fa-tags
  categories: /categories/ || fa fa-th
  archives: /archives/ || fa fa-archive
  #schedule: /schedule/ || fa fa-calendar
  sitemap: /sitemap.xml || fa fa-sitemap
  #commonweal: /404/ || fa fa-heartbeat

# Enable / Disable menu icons / item badges.
menu_settings:
  icons: true
  badges: false

Create the according blog pages using hexo. 

1
2
3
4
$ cd blog
$ hexo new page categories 
$ hexo new page tags 
$ hexo new page about

Add Tags

Open blog/source/tags/index.md file, by default it looks like below:

1
2
3
4
---
title: tags
date: 2022-07-20 00:05:23
---

Add type: tags so it looks like:

1
2
3
4
5
---
title: tags
date: 2022-07-20 00:05:23
type: tags
---

Go to a post article that want to add tags for, add a single tag: test or add multiple tags tag: [test1, test2].
Alt

Go to Tags Page on the menu, the tags show up successfully.
Alt

Add Categories

Very similar to tags, add type: categories to blog/source/categories/index.md file so it looks like:

1
2
3
4
5
---
title: categories
date: 2022-07-20 00:05:15
type: categories
---

Go to a post article header section and add categories: Hexo, now you have category set up as well.
Alt

Enable Article reads and total visits

Posted on Edited on In Disqus:

Background

Having previously used Vuepress to build Phonebox’s developer API documentation site, I came across another great product/framework for static website building, Hexo. For someone whose CSS skills can definitely be sharpened more, a static site generation framework like Hexo is great to create a customized internet presence.

Alt Text

For me, software development has never been just simply writing code. The amount of work takes to define product features, explore user case scenarios, document and diagram systems, design and architect solutions, insist on proper development methodologies, testing, launching, operation, collecting user feedbacks, etc, all are equally important. And undermining any could easily result in the difference between a project success or failure, or a startup surviving or closing-down. I will use this blog to write a mix of projects and industries that I have encountered in the tech career.

Most times I found programming at work is about following some documentation, running into errors, then searching and cracking until the error is cleared and the code is working as expected. And without further ado, I will go over quickly how I set up this Hexo Blog.

Step-by-Step Guide

Install hexo-cli using npm.

  1. Pre-requisite: homebrew, node and npm
  2. Install hexo-cli: npm install -g hexo-cli
  3. Initialize a hexo blog: hexo init blog
  4. To test hexo is installed successfully,
    a. Create a new hexo post: hexo new test_my_site
    b. Generate hexo websites: hexo g (hexo generate)
    c. Run Hexo locally: hexo s (hexo serve)
    d. View demo post: open localhost:4000 in browser
  5. 🥳🥳🥳🥳🥳🥳🥳🥳🥳🥳

Write blog using Markdown

Each post is written using markdown file. It might be slower to discuss complex business requirements, architecture design, or user case scenarios using Markdown where other tools such as Google Docs, Jira, and diagrams.net suit better. But markdown is great and convenient for writing technical documentation and guidelines. This is a great guideline for Markdown syntaxes.

Hexo also supports powerful customization through different themes. And each theme provides more features beyond the default theme.

Note here that Markdown has its limitations in supporting nested bullet points. So try to limit using too much nested bullet points or else hexo and the theme it’s using might experience error in rendering.

Change theme to Next theme

To add next as a theme, first install next. 

1
2
$ cd blog
$ git clone https://github.com/next-theme/hexo-theme-next themes/next

Note here that you may see some documents referencing another next-theme repo as https://github.com/next-theme/hexo-theme-next. This is a legacy repo that contains older version of next-theme. I have opened an issue on next-theme GitHub repo to address this.

Once next-theme has been installed under the path hexo-blog/themes/next. Go to Hexo config file _config.yml under the root directory and change the theme to next. theme: next
Alt Text

Configure Next theme to enable other features such as commenting.

First, you need to set up a Comment service. For this, I use Disqus. Follow the instruction on Disqus to set up a Disqus Service.
Once set up successfully, grab the short name generated by Disqus. It will be used to identify and connect your comment site to your blog site.

Here is a nice explanation on what is short name and how to configure trusted domain on Disqus.

Enable comment features in next-theme configuration by opening _config.ym; file in themes/next/_config.yml.
Alt Text
Under comments, set active to disqus. And u nder disqus, set the values to below:

1
2
3
4
disqus:
    enable: true
    shortname: [YourShortName]
    count: true

Alt Text

Save all, run $ hexo g, $ hexo s, open in browser.

There you have it, a next-theme powered hexo blog site running on local, with commenting feature enabled.
Alt Text

Hosting and Deploying

GitHub Pages
I host this site on GitHub Pages by creating a repo named [myGitHubUserName].github.io as requested. The GitHub instruction is very straight forward. Grab the repo link. Note: Must follow the naming convention [myGitHubUserName].github.io or it won’t work.

Config Deployment
Install hexo-deployer-git 

1
$ npm install hexo-deployer-git --save

Open the theme config file themes/next/_config.yml. under deploy, set the values to below: 

1
2
3
4
deploy:
    type: git
    repo: [YourGitHubPageRepo.git]
    branch: master

Deploy 

1
$ hexo clean && hexo g && hexo d

Visit your GitHub Page to see your blog live 🥳!

Custom Domain

Goggle Domain
I use Google Domain to register and maintain my personal domains.

Once domain has been created, two things should be configured ideally to make this work.

  1. Add a CNAME record under DNS config to point it to the GitHub page.
    Alt

  1. Create A records and point the custom domain to the IP address for GitHub Pages.
    Alt

Here is the official GitHub Pages documentations of setting up custom domain.

GitHub Pages Hosting
Navigate back to GitHub Pages Settings. Under pages, add the custom domain and make sure to enable Enforce HTTPS.
Alt

There are many other DNS services GoDaddy, Bluehost, HostGator, etc. A nice article briefly talks about DNS records.

Conclusion

A few things to note about when configuring the blog, themes, and writing in Markdown.

  1. I’ve noticed the blog behaves inconsistently when the Markdown article comes with too many nested bullet points. As much as I like to write a technical documentation using different headings, bullet points and table of contents, here it’s better to stay to simple headings and avoid nested bullet points to make sure the markdown article can render successfully.

  2. For next-theme there appear to be different sources of installation. And one of these sources is outdated legacy versions. See detail issue for why this happens. Make sure to download the latest stable release version.

  3. For many customization features, make sure the documentation works with the latest version of next-theme as well.

  4. A lot customization comes with modification to the next-theme‘s _config.yml file. And because this file was downloaded and installed directly from GitHub repo, any modifications to it is not easy to be uploaded to your own blog GitHub repo. Best to maintain a consistent local backup for it.

I plan to gradually add more features such as tagging, sidebar to this blog as I continue to fulfill this technical blog. I will also explore to add more interactive code blocks or design diagrams to help talk about some past projects and product features.