从Landscape迁移到Next——记一次Hexo主题更换

Posted on Edited on In , , , , Word count in article: 1.2k Reading time ≈ 4 mins.
  • 深色模式
  • 本地化默认 cdn 资源
  • 百度统计
  • LaTex 支持
  • LaTex SSR(Server Side Rendering)
next

起因

Landscape 在我这边有 font-awesome 的图标显示问题，但是 Github 上没有 issue，不确定是否为主题 bug，我自己魔改也是改了一大堆，自己引入了新的 fa lib 再修改图标 short cut

并且 Landscape 对中国的备案页脚，以及 katex/Mathjax 并无原生支持，调来调去比较麻烦

遂又找了个简洁明了又更加 modern 的主题，也就是现在使用的 Next

迁移过程

Part 1 安装

这个安装看Next官方doc就行，非常简单，为了方便起见我新建了一个 hexo 项目，再以 git 方式安装 Next，为了方便修改主题，如果你没有这个需求其实可以直接 npm 包安装

installation
1
2
3
npx hexo init hexo-site
cd hexo-site
git clone https://github.com/next-theme/hexo-theme-next themes/next

hexo-site 是根目录名

启用 Next 主题，也就是修改_config.yml，也就是 Hexo 的配置

_config.yml
1
2
3
4
...
-theme: landscape
+theme: next
...

同时将 themes/next 下的_config.yml 复制出来到项目的根目录底下，与_config.yml 同级, 命名为_config.my-next.yml 用于修改主题配置

Part 2 改 config，改主题，各种改

  • 参考 docs https://theme-next.js.org/docs/theme-settings/

以下仅展示关键配置

布局和深色模式

Next 原生提供了 4 种布局，参考官方的描述，这里我选择的是 Gemini 提供一个侧边栏，我觉得更加实用

  • Muse → Default Scheme, this is the initial version of NexT. Uses black-white tone and mainly looks cleanly.
  • Mist → A tighter version of Muse with a tidy single-column view.
  • Pisces → Double-column Scheme, fresh like your neighbor's daughter.
  • Gemini → Looks like Pisces, but have distinct column blocks with shadow to appear more sensitive to view.
_config.next.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
# ---------------------------------------------------------------
# Scheme Settings
# ---------------------------------------------------------------

# Schemes
-scheme: Muse
# scheme: Mist
# scheme: Pisces
+scheme: Gemini

# Dark Mode
-darkmode: false
+darkmode: true

实测这个改为 true 并不会强制 darkmode，而是会自动选择

菜单设置

也就是页面 sidebar 上面的东西

_config.next.yml
1
2
3
4
5
6
7
8
9
10
---
menu:
  home: / || fa fa-home
  about: /about/ || fa fa-user
  tags: /tags/ || fa fa-tags
  categories: /categories/ || fa fa-th
  archives: /archives/ || fa fa-archive
  #schedule: /schedule/ || fa fa-calendar
  sitemap: /sitemap.xml || fa fa-sitemap
  #commonweal: /404/ || fa fa-heartbeat
更改代码块主题

我个人喜欢 one-dark

具体主题选择和配置可以看 https://theme-next.js.org/highlight/

_config.next.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
codeblock:
  # Code Highlight theme
  # All available themes: https://theme-next.js.org/highlight/
  theme:
    light: atom-one-light
    dark: atom-one-dark
  prism:
    light: prism
    dark: prism-dark
  # Add copy button on codeblock
  copy_button:
    enable: true
    # Available values: default | flat | mac
    style:
  # Fold code block
  fold:
    enable: true
    height: 500
back to top 按钮
_config.next.yml
1
2
3
4
5
6
back2top:
  enable: true
  # Back to top in sidebar.
  sidebar: false
  # Scroll percent label in b2t button.
  scrollpercent: true
Mathjax 的配置

具体看 https://theme-next.js.org/docs/third-party-services/math-equations

  1. 安装新的 markdown 渲染器hexo-renderer-pandoc，原因是默认的渲染器会影响 LaTex 的解析与渲染
npm command
1
2
$ npm un hexo-renderer-marked
$ npm i hexo-renderer-pandoc

需要注意一点，这个渲染器需要你安装 pandoc，以渲染 LaTex
参考 https://github.com/jgm/pandoc/blob/master/INSTALL.md

随后你需要讲 pandoc 配置写入 Hexo 的配置文件_config.yml，其中 pandoc_path 是你 pandoc 安装位置

1
2
pandoc:
  pandoc_path: C:/Program Files/Pandoc/pandoc.exe

最后很重要的一步是清理 Hexo 缓存以及校验插件安装

1
hexo clean && hexo g -d
  1. 修改_config.next.yml
_config.next.yml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
math:
  # Default (false) will load mathjax / katex script on demand.
  # That is it only render those page which has `mathjax: true` in front-matter.
  # If you set it to true, it will load mathjax / katex script EVERY PAGE.
  every_page: false

  mathjax:
    enable: true
    # Available values: none | ams | all
    tags: none

  katex:
    enable: false
    # See: https://github.com/KaTeX/KaTeX/tree/master/contrib/copy-tex
    copy_tex: false
  1. 配置 SSR

这个 SSR 是以 SVG 形式渲染的，可以有更快的首屏，无需等待 LaTex 渲染，坏处是无法复制，无法交互，需要取舍
参考 https://github.com/next-theme/hexo-filter-mathjax

安装 filter 并清理缓存

npm command
1
2
npm install hexo-filter-mathjax
hexo clean

修改 math 配置

_config.next.yml
1
2
3
4
5
6
7
8
...
math:
...
+ every_page: false
mathjax:
- enable: true
+ enable: false
...

这里有个坑，启用 SSR 后，every_page 是 true 并不能启用页面的 mathjax，必须在页面的 front matter 上启用mathjax: true

展示一下效果

源码

markdown source code
1
2
3
4
5
6
7
8
9
10
11
12
$$
i\hbar\frac{\partial}{\partial t}\psi=-\frac{\hbar^2}{2m}\nabla^2\psi+V\psi
$$

$$
\begin{eqnarray*}
\nabla\cdot\vec{E}&=&\frac{\rho}{\epsilon_0}\\
\nabla\cdot\vec{B}&=&0\\
\nabla\times\vec{E}&=&-\frac{\partial B}{\partial t}\\
\nabla\times\vec{B}&=&\mu_0\left(\vec{J}+\epsilon_0\frac{\partial E}{\partial t}\right)\\
\end{eqnarray*}
$$
本地搜索的配置

参考 https://theme-next.js.org/docs/third-party-services/search-services

安装 npm 包

npm command
1
npm install hexo-generator-searchdb

修改 Next(_config.next.yml)以及 Hexo(_config.yml)的配置

_config.next.yml
1
2
3
4
5
6
7
8
9
---
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: true
  # Preload the search data when the page loads.
  preload: false
_config.yml
1
2
3
4
5
search:
  path: search.xml
  field: post
  content: true
  format: html
sitemap 配置

装包就行也不用配置什么

npm command
1
npm i hexo-generator-sitemap
标签和分类以及关于页面

这俩直接在 menu 里加了没用，要自己手动创建，当时找了半天

hexo command
1
2
hexo new page categoires
hexo new page tags

同时你需要修改这俩的 front matter

categories
1
2
3
4
5
6
---
title: categories
date:
+type: "categories"
...
---
tags
1
2
3
4
5
6
---
title: tags
date:
+type: "tags"
...
---

如果你需要关于（about）页面，方法与上述类似，先用hexo new page生成页面，再修改 front matter 并修改 type 为`"about"``

word counter 配置

也就是文章标题下显示的这个阅读时间和单词数量 参考 []

先装包

npm command
1
npm i hexo-word-counter

修改 Hexo 配置

_config.yml
1
2
3
4
5
6
symbols_count_time:
  symbols: true
  time: true
  total_symbols: true
  total_time: true
  awl: 4

修改 Next 配置

_config.next.yml
1
2
3
4
5
# Post wordcount display settings
# Dependencies: https://github.com/next-theme/hexo-word-counter
symbols_count_time:
  separated_meta: true
  item_text_total: true

Part 3 配置百度统计

修改 Next 配置

在此处添加你的百度站点验证码

_config.next.yml
1
2
3
# Baidu Webmaster tools verification.
# See: https://ziyuan.baidu.com/site
baidu_site_verification: [your verification code]

在此处添加你的百度统计 id

1
2
3
# Baidu Analytics
# See: https://tongji.baidu.com
baidu_analytics: [your analytics id]
防止本地测试运行时使用百度统计

此处需要修改主题源码

将 themes/next/layout/_third-party/analytics/baidu-analytics.njk 替换为如下内容

baidu-analytics.njk
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
{%- if theme.baidu_analytics %}
<script>
  var _hmt = _hmt || [];
  (() => {
    if (window.location.hostname.indexOf("localhost") == -1) {
      // check for localhost
      (function () {
        var hm = document.createElement("script");
        hm.src = "https://hm.baidu.com/hm.js?{{ theme.baidu_analytics }}";
        var s = document.getElementsByTagName("script")[0];
        s.parentNode.insertBefore(hm, s);
      })();
    }
  })();
</script>
{%- endif %}

图片显示问题

就现在新版本 Hexo 与 Next 来说，你只需要修改 Hexo 的配置，无需使用 image 显示插件了

_config.yml
1
2
3
4
...
-post_asset_folder: false
+post_asset_folder: true
...

然后千万记得hexo clean，我搁这卡了 1h

hexo command
1
hexo clean

总结

就这点东西，折腾了一晚上，next 的 config 有八九百行，也是看吐了 🤮，整博客的乐趣和成就感还是在于折腾啊