Introduction

Hexo is a fast and powerful Node.js blog framework. You can write blog posts in Markdown and Hexo will generate static HTML (along with CSS, JavaScript) files with a custom beautiful theme in seconds. You can then deploy these static files online with services like GitHub Pages, Vercel or Netlify.

Installation

Before installing Hexo, you should have Node.js and Git installed first.

In the terminal, enter the commands below to install Hexo

npm install -g hexo-cli

Then initialize a folder for your blog

hexo init <folder name>

Enter the folder

cd <folder name>

Customization

The Hexo framework provides multiple blog themes that you can choose from to customize your blog. The theme that I have chosen is the Butterfly theme.

For more customization tips, please refer to the guide for your selected theme.
Link to Butterfly theme customization guide

Theme Installation

  1. In Hexo root file, install Butterfly theme:
git clone -b master https://github.com/jerryc127/hexo-theme-butterfly.git themes/butterfly
  1. In _config.yml, change theme to butterfly.
theme: butterfly
  1. In Hexo root directory, create a new theme config file _config.butterfly.yml. Then install pug and stylus
npm install hexo-renderer-pug hexo-renderer-stylus --save

Custom Fonts

The fonts that I use for my blog is PT Serif and Noto Serif SC by Google Fonts.

  1. In _config.butterfly.yml, change the global font settings
font:
  global-font-size: 17px
  code-font-size: 16px
  font-family: PT Serif, Noto Serif SC
  code-font-family: consolas
  1. Embed the font as follow in _config.butterfly.yml
inject:
  head:
    <link rel="preconnect" href="https://fonts.googleapis.com">
    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
    <link href="https://fonts.googleapis.com/css2?family=Noto+Serif+SC&display=swap" rel="stylesheet">
    <link href="https://fonts.googleapis.com/css2?family=PT+Serif&display=swap" rel="stylesheet">

KaTex Support

KaTex is a JavaScript library that displays mathematical notation in web browsers.

  1. Enable KaTex in blog post metadata
---
title: 'Post title'
date: 2023-1-1 00:00:00
categories: "Test"
description: A test 
cover: 
tags: 
katex: true
---
  1. Uninstall previous Hexo markdown rendered and install other plugins.
npm un hexo-renderer-marked --save # Uninstall this if you have it
npm un hexo-renderer-kramed --save # Uninstall this if you have it

npm i hexo-math --save 
npm i hexo-renderer-markdown-it-plus --save # Install this renderer plugin
npm install katex @renbaoshuo/markdown-it-katex # Install this katex plugin
  1. Add the code given below at the bottom of configuration file _config.yml.
math:
  engine: katex
  katex:
    css: https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/katex.min.css
    js: https://cdn.jsdelivr.net/npm/katex@0.10.0/dist/katex.min.js
    config:
      # KaTeX config
      throwOnError: false
      errorColor: "#cc0000"


markdown:
    plugins:
      - '@renbaoshuo/markdown-it-katex'

Writing A New Post

To write a new blog post, insert a new Markdown file (for example: blog_post_name.md) into the source/_posts directory. Then, insert .yaml metadata at the top of your Markdown post.

---
title: 'Post title'
date: 2023-1-1 00:00:00
categories: "test"
description: A test 
cover: 
tags: 
toc_number: true
katex: true
---



# Heading 1
Some text here for your blog post.

If you’re unfamiliar with Markdown syntax, you can refer to this guide.

Deployment

Deploy and preview on a local server

Install plugins and run server

npm install hexo-server --save
hexo server

Your blog should start running locally at http://localhost:4000/

Deploy to GitHub and Vercel

Create a GitHub repository for your blog.

Then, install Hexo plugins:

npm install hexo-deployer-git --save

In _config.yml configure the deploy settings

deploy:
type:git
repo: <repository link>
branch: main

Run commands to clean database, generate new static HTML files from your Markdown files, and then deploy them to GitHub.

hexo clean
hexo generate 
hexo deploy

Finally, create a new Vercel project from your blog’s GitHub repository.

Your blog should start running online now at Vercel’s given link https://<project_name>.vercel.app.

If any issues occur while deploying, you can refer to some of these articles below:

git config --global http.version HTTP/1.1
git config --global --unset http.proxy
git config --global --unset https.proxy

SEO

SEO stands for search engine optimization, which is improving your website to increase its chances of ranking higher in Google or other search engines.

sitemap.xml

Sitemaps are files where you provide information about the pages, videos, and other files on your site, and the relationships between them. Search engines read this file to crawl your site more efficiently.

Install this Hexo plugin to automatically generate sitemaps for your blog

npm install hexo-generator-sitemap --save

In _config.yml file, change the permalink

permalink: :title/

and also add this piece of code

sitemap:
  path: sitemap.xml

robots.txt

A robots.txt file tells search engine crawlers which URLs the crawler can access on your site.

Under your /source folder, create your own robots.txt file and then copy the code below into it

User-agent: *
Allow: /
Allow: /archives/
Allow: /categories/
Allow: /tags/
Allow: /about/

Disallow: /vendors/
Disallow: /js/
Disallow: /css/
Disallow: /fonts/
Disallow: /vendors/
Disallow: /fancybox/

Sitemap: https://blog.jinny.work/sitemap.xml

Then go to https://search.google.com/search-console and add your domain and sitemap.

Code compression

Minimizing or compressing your code can make your website load faster.

Install this Hexo plugin to automatically make your code neat

npm install hexo-neat --save

In your _config.yml file, add these settings

neat_enable: true
neat_html:
  enable: true
  exclude:
neat_css:
  enable: true
  exclude:
    - '**/*.min.css'
neat_js:
  enable: true
  mangle: true
  output:
  compress:
  exclude:
    - '**/*.min.js'
    - '**/index.js'

Adding A Search Function

Install Hexo plugin

npm install hexo-generator-search --save

In _config.yml, add these settings:

search:
  path: search.xml
  field: post
  format: html
  limit: 10000

Then enable local search in _config.butterfly.yml

local_search:
  enable: true
  preload: false