hugo-theme-reimu Migration Guide

This article documents the differences between hugo-theme-reimu and hexo-theme-reimu themes, and how to migrate articles from hexo-theme-reimu to hugo-theme-reimu.

Github

https://github.com/D-Sketon/hugo-theme-reimu

This article assumes you have already installed the hugo-theme-reimu theme and created your own configuration file following the guide.

Differences between Hexo and Hugo

• Hugo doesn’t support Hexo’s multi-level categories, only single-level categories and tags are supported
• Hugo doesn’t support Hexo’s monthly and yearly archives

Basic Structure

The basic structure differs between hugo-theme-reimu and hexo-theme-reimu themes:

• Original _config.reimu.yml migrates to config/_default/params.yml
• vendor configuration from original _config.reimu.yml migrates to data/vendor.yml
• Original source/_data/covers.yml migrates to data/covers.yml
• Original source/friend/_data.yml migrates to data/friends.yml
• Original source/_data/avatar/avatar.webp migrates to static/avatar/avatar.webp

Basic Configuration Changes

Hugo adds the following new configurations:

+ mainSections: ["post"] # Specify main sections, referring to article writing folders
+ yearFormat: "2006" # Year format
+ monthFormat: "2006-01" # Month format
+ dateFormat: "2006-01-02" # Date format
+ timeFormat: "2006-01-02 15:04:05" # Time format

+ author: D-Sketon # Originally from Hexo _config.yml's author
+ description: "少女祈祷中..." # Originally from Hexo _config.yml's description
+ subtitle: "少女祈祷中..." # Originally from Hexo _config.yml's subtitle

(Compared to < v1.0.0, after v1.0.0 hexo and hugo unified configurations) Changed the menu configuration structure:

menu:
-  home: /
-  archives: /archives
-  about: /about
-  friend: /friend
+  - name: home
+    url: ""
+  - name: archives
+    url: "archives"
+  - name: about
+    url: "about"
+  - name: friend
+    url: "friend"

Additionally, all paths in the configuration are relative paths and don’t need leading /:

- banner: "/images/banner.webp"
+ banner: "images/banner.webp"

Widget

Widget removed the archive configuration:

widgets:
-   - archive

Removed archive_type and show_count configurations:

- archive_type: "monthly"
- show_count: false

favicon

Now uses static/favicon.ico as the default favicon, no longer supports favicon configuration.

- favicon: "/images/favicon.ico"

Open Graph

Removed default_og_image configuration, now uses banner as the default Open Graph image.

open_graph:
  enable: true
  options:
-     default_og_image: /images/banner.webp

Site Search

Local search is not supported, only Algolia search is supported.

- generator_search:
-   enable: false

Since hugo.toml cannot be read, Algolia needs additional appID, apiKey, and indexName configurations:

algolia_search:
  enable: false
+   appID:
+   apiKey:
+   indexName:

Math Formulas

Now uses Front Matter to enable formula rendering, math.enable configuration removed.

• KaTeX only supports client-side rendering, so math.katex.autoRender configuration removed.
• MathJax3’s options configuration needs to be wrapped in [] (excluding Hugo’s built-in configuration reading logic).

math:
-   enable: true
  katex:
    enable: true
-    autoRender: false
  mathjax:
    enable: false
-     options: { tex: {} }
+     options: [{ tex: {} }]

Mermaid

Original configuration removed. Now uses Front Matter to enable Mermaid.

- mermaid:
-   enable: true # default true

RSS

Hugo supports RSS by default, original configuration removed.

- rss: atom.xml