Building a Professional Blog With Hexo and Theme-NexT

Posted on Edited on In Views: Disqus: Word count in article: 1.7k Reading time ≈ 6 mins.

Build a professional blog with Hexo and Theme-NexT. This guide covers installation, configuration, and essential integrations like SEO, analytics, and custom plugins to elevate your writing experience.

Component Version
hexo 7
hexo-theme-next 8
NODE_VERSION 24

Getting Started

Initialize your Hexo blog system 

1
2
3
4
5
6
7
❯ npm install hexo-cli -g
❯ hexo init # Initial the project  
❯ npm install # download the independencies  
❯ tree ./ -L 1 #  Just review the file tree  
❯ hexo g # Generate the html  
❯ hexo s # Start the server  
❯ code _config.yml # custom your blog

NOTICE:
Hexo init should be run in the empty folder.

Mermaid Diagrams

Hexo Next already supported the mermaid nested, here is the guideline:
https://theme-next.js.org/docs/tag-plugins/mermaid

and we needn’t install additional plugin for it.

npm install hexo-filter-mermaid-diagrams save

RSS Feed

Installation

1
❯ npm install hexo-generator-feed --save

Configuration

Config feed file in {ROOT}/_config.yml, refer to the link below:
https://github.com/hexojs/hexo-generator-feed

Config the RSS link icon in the social section:

In {ROOT}/_config.next.yml
or
In {ROOT}/themes/theme_next/_config.yml

1
2
social:
  RSS: /atom.xml || fa fa-rss

Theme Customization

Here we use the theme-next as the example.
Installation

1
2
❯ cd hexo-site
❯ npm install hexo-theme-next

Configuration
Change the content in the _config.yml

1
theme: next
1
❯ hexo clean # rememeber to clean public/

Refer to the official site of theme-next:
https://theme-next.org
https://github.com/next-theme/hexo-theme-next

Avatar Settings

Add the url into the Avatar section in the _config

1
2
3
4
5
6
7
8
9
# Sidebar Avatar
avatar:
  # Replace the default image and set the url here.
  # url: #/images/avatar.gif
  url: https://s.gravatar.com/avatar/***
  # If true, the avatar will be displayed in circle.
  rounded: true
  # If true, the avatar will be rotated with the cursor.
  rotated: false

Create your gravatar account here:
https://en.gravatar.com/emails/

Cloudflare Analytics

Enable with JS Snippet installation in the dashboard of cloudflare analytics,
then you would get a the JS Snippet needs to be installed manually.

1
<!-- Cloudflare Web Analytics --><script defer src='https://static.cloudflareinsights.com/beacon.min.js' data-cf-beacon='{"token": "301040bd778923748972389sdfsdf105d8"}'></script><!-- End Cloudflare Web Analytics -->

the token value is unique for your site and that is what we need to config in the theme-next.

Config the cloudflare analytics in the _config.next.yml of theme-next

1
2
3
# Cloudflare Web Analytics
# See: https://www.cloudflare.com/web-analytics/
cloudflare_analytics: 301040bd778923748972389sdfsdf105d8

Google Fonts

Prevew the google fonts here:
https://fonts.google.com/

Enable Google Fonts in the _config.next.yml of theme-next

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
font:
  enable: true

  # Uri of fonts host, e.g. https://fonts.googleapis.com (Default).
  # https://www.googlefonts.cn
  host: https://fonts.font.im

  # Font options:
  # `external: true` will load this font family from `host` above.
  # `family: Times New Roman`. Without any quotes.
  # `size: x.x`. Use `em` as unit. Default: 1 (16px)

  # Global font settings used for all elements inside <body>.
  global:
    external: true
    family: Noto Sans
    # family: Lato
    size: 0.8

  # Font settings for site title (.site-title).
  title:
    external: true
    family: Sofadi One
    size: 2

  # Font settings for headlines (<h1> to <h6>).
  headings:
    external: true
    family: Raleway
    size: 

  # Font settings for posts (.post-body).
  posts:
    external: true
    family: 
    size: 

  # Font settings for <code> and code blocks.
  codes:
    external: true
    family: Google Sans Code

Categories and Tags

Categories apply to the posts in order, resulting in a hierarchy of classifications and sub-classifications.
Tags are all defined on the same hierarchical level so the order in which they appear is not important.

Example 

1
2
3
4
5
6
7
8
9
10
# Baseball is a sub-category of Sports. 
# Injury, Fight, and Shocking are tags associated with the post in the same hierarchical level.    

categories:
- Sports
- Baseball
tags:
- Injury
- Fight
- Shocking

The classification records in the front-matter of the the source of markdown file
https://raw.githubusercontent.com/qzi/qzi.github.io/hexo/source/_posts/technology/hexo-go.md

Front-matter is a block of YAML or JSON at the beginning of the file that is used to configure settings for your writings. Front-matter is terminated by three dashes when written in YAML or three semicolons when written in JSON.
https://hexo.io/docs/front-matter.html

Display in the menu

Config in the [hexo_project]/_config.next.yml

1
2
3
menu:
  tags: /tags/ || fa fa-tags
  categories: /categories/ || fa fa-th

Markdown Editors

Typora

Typora is a what you see is what you get editor for markdown file.

Here is my another tutorial for Typora
https://leonvision.online/technology/wysiwyg-markdown-editor-typora/

and visual studio code with markdown plugin is also another alternative choice.

Visual Studio Code

Visual Studio Code comes with a powerful built-in markdown preview feature. Simply press Cmd+Shift+V on macOS to toggle the preview panel for your markdown file.

To customize the preview styling to match your Hexo blog’s appearance, create a .vscode/markdown.css file in your project root and reference it in .vscode/settings.json:

1
2
3
4
5
{
    "markdown.styles": [
        ".vscode/markdown.css"
    ]
}

markdown.css: Here is the example of markdown.css for vscode

Showing Whitespaces Explicitly
Cmd + Shift + P → “View: Toggle Render Whitespace”

Auto-Insert Markdown Line Breaks
Configure a keyboard shortcut to automatically insert two spaces and a newline when pressing Shift + Enter:

Cmd + Shift + P → “Preferences: Open Keyboard Shortcuts (JSON)” and add:

1
2
3
4
5
6
{
  "key": "shift+enter",
  "command": "type",
  "args": { "text": "  \n" },
  "when": "editorTextFocus && editorLangId == 'markdown'"
}

Now press Shift + Enter to insert a hard line break in Markdown files.

Search

Enable the feature of local serach in the _config.next.yml of theme-next 

1
2
3
4
5
6
7
8
9
10
# Local Search
# Dependencies: https://github.com/next-theme/hexo-generator-searchdb
local_search:
  enable: true
  # Show top n results per article, show all results by setting to -1
  top_n_per_article: 1
  # Unescape html strings to the readable one.
  unescape: false
  # Preload the search data when the page loads.
  preload: true

Post Excerpt

Manually add excerpt in the front-matter of the markdown file 

1
2
3
4
5
---
title: 中文等宽字体（Monospace Chinese Font Family）
date: 2019-12-26 00:52:18
excerpt: ' 中文等宽字体，一个中文字符等宽两个英文字符，Mac下很多字体（ Menlo, Monaco, Courier New, Source Code Pro ）没有严格遵循或者说达不到这个标准, 它们不包括CJK的字库，有的时候用一些 markdown table formatter 会导致不整齐，其实并不是排列不整齐，而是字体的宽度不同 '
---

Configuration

Config in the [hexo_project]/_config.next.yml

1
2
3
4
5
6
# Automatically excerpt description in homepage as preamble text.
excerpt_description: true

# Read more button
# If true, the read more button will be displayed in excerpt section.
read_more_btn: true

Refer to https://hexo.io/docs/tag-plugins#Post-Excerpt

Asset Links

Installation 

1
❯ npm i --save hexo-asset-link

Configuration
Config in the [hexo_project]/_config.yml

1
2
3
...
post_asset_folder: true
...

Markdown Syntax

1
2
![Rest Client](./my-favorite-extensions-for-visual-studio-code/rest-client.jpg)
![Rest Client](my-favorite-extensions-for-visual-studio-code/rest-client.jpg)

Reference
homepage of hexo-asset-link
https://github.com/liolok/hexo-asset-link

Custom Domain Email Forwarding

Cloudflare offers free email forwarding for custom domains.
There is a another article for it: Custom domain email forwarding

Sitemap and SEO

Installation

1
❯ npm install hexo-generator-sitemap --save

Configuration
Config in the [hexo_project]/_config.yml

1
2
3
4
5
6
7
8
9
10
11
# hexo-generator-sitemap
# https://github.com/hexojs/hexo-generator-sitemap
sitemap:
  path: 
    - sitemap.xml
    - sitemap.txt
  template: null
  template_txt: null
  rel: false
  tags: true
  categories: true

and then submit the url of sitemap to google search console to improve your performance on Google Search.
https://search.google.com/search-console/

Google AdSense

Register the account of google adsense and generate a unique in-article ads code snippet for your site. f

Uncomment the custom_file_path in ./_config.next.yml

1
2
custom_file_path:
  postBodyEnd: source/_data/post-body-end.njk

Create a new file source/_data/post-body-end.njk
Paste the code snippet of in-article ads from google adsense into post-body-end.njk

More detail in google-analytics-and-adsense-in-hexo

Google Analytics

Register the account of google analysis and get the TAG ID for your site.
Config in {hexo_root}/_config.next.yml

1
2
3
4
5
6
7
8
9
10
# Google Analytics
# See: https://analytics.google.com
google_analytics:
  tracking_id: TAG-ID
  # tracking_id: # <app_id>
  # By default, NexT will load an external gtag.js script on your site.
  # If you only need the pageview feature, set the following option to true to get a better performance.
  only_pageview: false
  # only needed if you are using `only_pageview` mode, https://developers.google.com/analytics/devguides/collection/protocol/ga4
  measure_protocol_api_secret:

Comment Systems

Disqus

Disqus can allow the anonymous comment, but it is blocked in China mainland.

Here is a guide to setup Disqus in Hexo with Theme-NexT:
Add Comments Section to Your Hexo Blog

Configuration in the {hexo_root}/_config.next.yml

1
2
3
4
5
# For more information: https://disqus.com
disqus:
  enable: true
  shortname: shortname_of_your_site
  count: true

Auto-Update Timestamp

I developed a new vscode extension - Hexo Auto Updated to update last modified date and time automatically when we saved the markdown file.
Link to Hexo Auto Updated

Video Embedding

Open the video in youtube, click the share button to get the embed code snippet.
Paste the code snippet into the markdown file directly.

1
<iframe width="560" height="315" src="https://www.youtube-nocookie.com/embed/E46_veB0DPU" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen></iframe>

Force Refresh

Presss Shift + Command + r to force to refresh the browser(Chrome) to test the result in Mac

Presss Option + Command + r to force to refresh the browser(Safari) to test the result in Mac 

1
2
3
4
5
# clean the desktop before we work
❯ rm -rf node_modules
❯ rm -f package-lock.json
❯ npm cache clean --force
❯ npm install

References