Writing & Wiki Guide

This page covers how to write blog posts and wiki pages, including multi-language conventions and gotchas.

1. Writing a Post

1.1 Creating a Post

hexo new post "Post Title"
# Generates source/_posts/post-title.md (filename auto-lowercased on build)

Posts live in source/_posts/ with no subdirectories needed.

1.2 Minimal Front-matter

---
layout: post
title: Post Title
categories:
  - Category Name
tags:
  - tag1
  - tag2
---

Other useful fields:

Full field reference (23 fields) see Directory Structure §4.

1.3 abbrlink (Permalink)

Permalink format is posts/:abbrlink/ (e.g. /posts/13894dce/). The abbrlink is generated by the hexo-abbrlink plugin on first build and written into front-matter (with writeback: false it is no longer written back, the field is fixed). Never manually edit the abbrlink of an existing post — doing so permanently breaks the link.

1.4 Content Syntax

Posts and wiki pages use the same Markdown renderer (hexo-renderer-markdown-it), supporting all markdown-it plugins and 14 matery tag plugins. See Markdown Syntax and Content Tag Plugins for details.

2. Wiki Frontmatter

Wiki pages must include:

---
title: Page Title
layout: wiki        # required: wiki layout (3-column + sidebar)
wiki: tutorial      # required: wiki sub-site (docs / api / tutorial)
---

English versions must also include lang: en (otherwise sidebar links fall back to the Chinese path):

---
title: Page Title
layout: wiki
wiki: tutorial
lang: en            # required for English pages
---

Optional fields are same as blog posts (toc / mathjax / mermaid / echarts / closeAutoTocNum / comment etc.). Wiki pages also support disabling comments via front-matter comment: false (handled by post-filter.js).

Wiki pages support the same Markdown syntax as blog posts:

• All markdown-it plugins: emoji / abbr / footnote / task lists / tables / containers / math ($...$)
• 14 matery tag plugins: {% note %}, {% tabs %}, {% timeline %}, {% mermaid %}, {% button %}, {% label %}, {% groupimage %}, {% wechat_dialog %}, {% cardurl %} etc.
• Container syntax (:::): ::: tip / ::: warning / ::: note / ::: info / ::: attention / ::: error / ::: hint

3. Multi-language Support

3.1 Wiki Directory Structure

Each wiki sub-site lives under source/{wiki}/ (e.g. source/tutorial/); the English version goes to source/en/{wiki}/:

source/tutorial/guide/writing.md     # Chinese (default lang, no prefix)
source/en/tutorial/guide/writing.md  # English (/en/ prefix, must include lang: en)

3.2 URL Rules

3.3 Fallback

• With English version (source/en/ file exists) → /en/... shows English
• Without English version → /en/... falls back to Chinese + top banner (“This page has no en version yet, showing default language content”), with noindex to prevent SEO duplication
• Translation source convention: source/en/{wiki}/{page}.md — just add the translated file, no config change needed

3.4 Writing Tips

1. Default language first: write Chinese first, then add English
2. English sidebar keys: use snake_case keys in source/_data/{wiki}-sidebar.yml (e.g. getting_started); display text comes from languages/*.yml
3. Internal links: use absolute paths + .html (e.g. /tutorial/guide/writing.html) — language prefix is added automatically
4. After adding a page: update source/_data/{wiki}-sidebar.yml

Note: source/_data/{wiki}-sidebar.yml is this theme’s sidebar convention — most Hexo blogs maintain their sidebar in the theme config or templates instead; this theme keeps one data file per wiki under _data/ for separate management.

3.5 Post Translation

Blog posts can also have multi-language versions. Translation files go under source/{lang}/_posts/, with the same filename as the Chinese original:

---
layout: post
title: Post Title (English)
abbrlink: 13894dce      # must match the Chinese original
lang: en
categories:
  - Category Name
tags:
  - tag1
  - tag2
---

The abbrlink is generated by the hexo-abbrlink plugin on first build and written into front-matter (with writeback: false it is no longer written back, the field is fixed). Never manually edit the abbrlink of an existing post.

4. Heading Numbering Gotcha (Important)

• Theme has CSS auto-numbering (on by default): auto-numbers h2-h6 (1., 1.1, 1.1.1…)
• Manually numbered headings (e.g. ## 1. Overview, ### 1.1 Background) will double-number with CSS auto-numbering (renders as 1. 1. Overview)
• Manually numbered pages must set closeAutoTocNum: true (frontmatter) to disable CSS auto-numbering
• Pages relying on CSS auto-numbering should not set that field

5. Verification

• Local build: after npm run build, visit /tutorial/xxx and /en/tutorial/xxx and confirm both versions render correctly
• Multi-language: add a test page under source/en/tutorial/ with proper front-matter and confirm /en/tutorial/<name> shows English; then visit an untranslated page and confirm it shows the default-language content plus the top fallback banner
• English lang: en: verify all source/en/tutorial/**/*.md files include lang: en — without it, sidebar links fall back to the Chinese path (/docs/ instead of /en/docs/)
• Sidebar translations: for each language you enabled, check that languages/*.yml has the matching sidebar.tutorial.* entries, so no raw keys appear in the sidebar