Installation & Theme Setup

This article explains how to build a Hexo site using the matery theme from scratch and complete the basic configuration.

1. Create a Hexo Site

hexo init my-blog
cd my-blog
npm install

hexo init automatically clones hexo-starter and installs dependencies. When done, the directory already contains _config.yml (site config), source/ (content), themes/ (themes) and other basic structures.

2. Install the matery Theme

Clone the theme to themes/matery:

git clone https://github.com/blinkfox/hexo-theme-matery.git themes/matery

This blog uses a deeply customized matery (far more features than upstream), managed as a git submodule:

git submodule add ssh://git@git.17lai.online:222/work/matery.git themes/matery

The customized version is NOT compatible with upstream. Replacing it with the upstream original will lose many features — do not mix them.

3. Basic Root _config.yml Configuration

Edit the site root _config.yml:

# Enable the matery theme
theme: matery

# Site language (matery Chinese interface)
language: zh-CN

# Site basic information
title: 夜法之书
subtitle: 深度思考，深入生活
description: 个人独立技术博客
author: appotry

The theme’s own detailed configuration lives in themes/matery/_config.yml (about 3000 lines in this blog, including menu, comments, CDN, effects, etc.). During CI builds it is overwritten by the userConfig/_config.tmp.yml template, so for daily development, edit the template file instead.

4. Create Required Pages

The matery theme menu depends on several standalone pages. Create them with hexo new page:

hexo new page about
hexo new page tags
hexo new page categories
hexo new page friends
hexo new page galleries

The files generated by hexo new page only contain title and date — you must manually add the layout field (otherwise the page will not render with the corresponding layout):

Create individual gallery pages with hexo new gallery <name> (layout: gallery; encrypted galleries can add password in front-matter).

5. Install Key Dependencies

Add the following dependencies to package.json and run npm install. Below are the core dependencies used by this blog and their purposes:

Markdown Rendering Enhancement Plugins

hexo-renderer-markdown-it works with the following markdown-it plugins for a rich writing syntax:

• markdown-it-mathjax3: $...$ inline / $$...$$ block math formulas
• markdown-it-mermaid: Mermaid diagrams (with front-matter mermaid: true)
• markdown-it-emoji, markdown-it-footnote, markdown-it-task-checkbox
• markdown-it-container, markdown-it-admon: callout blocks / notes
• markdown-it-ins, markdown-it-mark, markdown-it-sub, markdown-it-sup: text enhancements
• markdown-it-multimd-table: enhanced tables (merged cells etc.)

Post Encryption

Post encryption is provided by the in-house HBE v4 system (AES-256-GCM + PBKDF2, replacing the removed hexo-blog-encrypt plugin since 2026-08-09; configured in the encrypt: section of the theme config template userConfig/_config.tmp.yml):

encrypt:
  enable: true
  tags:
    - {name: 私人, password: "your password"}

Encryption methods: front-matter password (whole post) / {% encrypt %} tag (snippet) / encrypt_password in {wiki}-sidebar.yml (whole wiki). See §8 of the “Layout & Pages” chapter.

• Tag-based encryption: a post with an encrypted tag is encrypted automatically
• Per-post encryption: write password: "your password" in front-matter (SHA256 form in the scaffold)

6. Local Preview & Verification

hexo clean && hexo generate   # or npm run build
hexo server                   # http://localhost:4000/

Open http://localhost:4000/ and check the homepage, tags page, categories page, about page etc. Once everything looks right, deploy via hexo deploy or push to GitHub for Vercel to build and go live.

Troubleshooting: if pages don’t update after changing config/templates, run hexo clean then hexo generate; after modifying source/_data/*.yml data files, delete db.json before generating.

Next Steps

• Directory Structure & Content Management: file layout, writing workflow, front-matter reference