Hexo Next

Posted on Edited on In Views:

在之前的文章中, 我介绍了如何使用Hexo来构建静态站点. Hexo有很多主题, 其中我认为最好看最好用的是Hexo Next theme. 本文介绍如何使用和配置Next theme, 以及如何对Hexo和Next进行多主机同步.

Refs:

  • NeXt Tutor, 里面有几乎全部的主题配置教程
  • 最新版(v8)NeXt Github仓库
  • Next Official Blog
  • Awesome NexT : 有很多别人的Next博客, 非常值得借鉴

Intro

My Dependency Version:

  • Next Version: 8.15.1

  • Hexo Version: 6.2.0

  • hexo-cli Version: 4.3.0

在本文中, 除非特殊说明, 否则编辑的都是主题配置文件( aka NexT _config.yml ), 由于使用了Alternate Theme Config, 因此主题配置文件位置是<hexo>/_cofig.next.yml.

Config File Features

在之前关于Hexo的文章中, 我说过主题目录(<hexo-dir>/themes/next)和网站目录(<hexo-dir>/)是不同的. 主题的配置文件, 样式文件等, 都在主题目录下, 因此如果想要修改主题的配置, 也需要更改主题目录下的对应文件.

但是, 下文会讲到, 主题要么用npm下载, 要么用git下载, 无论哪种方式都会对主题进行版本管理. 我用的是git, 对主题目录下的文件做的更改会在之后git pull时被上游仓库的代码覆盖. 这使得对主题做自定义的配置很麻烦.

为此, Next提供了 Alternate Theme Config, Data Files 和 Custom Files feature, 使得我们可以把Next的配置文件, 样式文件和其他的文件copy到<hexo-dir>/source/_data/(这就是 Data Files), 然后修改Data files, 并让用它们来覆盖主题目录下的对应文件(这就是 Custom Files )被加载.

因此, 所有对主题的变更都会放在网站目录而不是主题目录, 主题目录下的内容不需要做变动, 可以很方便地进行版本管理.

  • Alternate Theme Config: Next的配置文件可以放在<hexo>/_cofig.next.yml,这会覆盖<hexo-dir>/themes/next/_config.yml.
  • Data Files: 可以把Next的样式文件放在<hexo-dir>/source/_data/
  • Custom Files: 可以在Next配置文件中, 指定Data files来替换掉主题目录下的对应文件.

当然了, 不是所有主题都像Next一样提供了这些机制. 在这些主题中, 要想对主题做更改, 就得改主题目录下的文件. 此时如果要接受主题官方的更新, 就得把原来的主题目录备份, pull更新后再仔细地修改回去, 这非常麻烦. 对于这种情况, 我的建议是:

  • 要么别对主题做任何修改.
  • 要么就不接受官方的更新, 直接把官方主题fork下来作为自己的仓库, 之后就和这个仓库做同步, 也就是对主题做单独的版本管理.

Alternate Theme Config

  1. 把主题配置文件复制到Hexo项目目录下, 取名为 _config.[name].yml. Replace [name] with the value of theme option in Hexo config file. For NexT theme, the file name is _config.next.yml by default

  2. 现在主题的配置文件就会读取Hexo项目目录的_config.[name].yml, 而不是主题目录的_config.yml. 由于位于Hexo项目目录下, _config.[name].yml会随着每次的push被push到Hexo项目的仓库. 不用担心子项目问题

  3. 多主机同步时, 新主机只需clone整个项目:

    1
    git clone https://github.com/LYK-love/LYK-love.github.io

Next Doc

  • Next Official Doc
  • Next Github Repo

尽量以官方文档为准, Github repo上只有很少的信息. 此外, Next在Github上存在多个Github repo, 除了Next Github Repo之外的Repo都已经过时了, 请不要被混淆. 例如该repo:

  • https://github.com/theme-next/hexo-theme-next

就是一个过时的repo, 其next版本只到7.8.0. 而直到本文写作时, next版本已经达到8.15.1了, 因此要注意区分.

Version

NeXt < 8 好像没办法查看版本

Next >=8 之后, 每次hexo s/d时在命令行的输出里都有Next版本信息. 此外hexo version也会显示next版本.

Installation

Next Official Doc: Installation

无论是下载还是更新Next, 都要先更新到最新的Hexo.

为了及时收到Next官方的更新, 我就不单独开一个github仓库对主题做版本管理了.

Using npm

1
npm install hexo-theme-next@latest
  • npm会把主题文件夹下载到/node_modules/hexo-theme-next

Using git

In hexo directory:

1
git clone https://github.com/next-theme/hexo-theme-next themes/next
  • 注意, 如果在themes/下已经存在了主题文件夹, 则Hexo会忽略node_modules/中可能存在的主题文件夹, 使用themes下的. 也就是说git安装的主题会覆盖npm安装的主题.
  • 我选择用git来安装, 原因是这样做可以比较方便地跳转到主题目录去看Next的源代码.

After Installation

安装成功后就可以使用了, 命令行输入如下:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
❯ hexo s
INFO  Validating config
INFO  ==================================
  ███╗   ██╗███████╗██╗  ██╗████████╗
  ████╗  ██║██╔════╝╚██╗██╔╝╚══██╔══╝
  ██╔██╗ ██║█████╗   ╚███╔╝    ██║
  ██║╚██╗██║██╔══╝   ██╔██╗    ██║
  ██║ ╚████║███████╗██╔╝ ██╗   ██║
  ╚═╝  ╚═══╝╚══════╝╚═╝  ╚═╝   ╚═╝
========================================
NexT version 8.15.1
Documentation: https://theme-next.js.org
========================================
INFO  Start processing
INFO  Hexo is running at http://localhost:4000/ . Press Ctrl+C to stop.

Upgrade

已经采用了Alternate Theme Config, 因此可以平滑地升级:

1
2
3
cd hexo-site
cd themes/next
git pull origin master

保险起见, 可以备份old主题文件夹的文件, 把旧主题文件夹rename为next-old. 当然, 我不会更改主题目录下的任何文件, 因此不备份也没关系.

Next Theme Config

进阶配置

  • Important: 关闭页面动画效果:

    1
    2
    3
    4
    5
    6
    # Use Animate.css to animate everything.
    # For more information: https://animate.style
    # 千万不要打开, 否则页面每次跳转都会有个渐变效果, 慢得要死. 关闭后网站速度会大幅提升.
    motion:
      enable: false
      async: false

    实测这样做会让网站速度大幅提升, 彻底达到可用水平.

  • Scheme: 目前觉得Mist比较好看.

    1
    2
    3
    4
    5
    # Schemes
      # scheme: Muse
      scheme: Mist
      # scheme: Pisces
      # scheme: Gemini

  • 设置语言: 我使用默认的英语. 如果要使用汉语, 可以编辑主题配置文件:

    1
    language: zh-CN

  • 首页文章显示摘要: 在文章中适当位置插入 <!--more-->，该位置之前的部分即为摘要，会显示在首页中.

  • sidebar社交链接: 邮箱前要加mailto:, 这还是我用开发者工具查别人的网站发现的..( 其实mailto是html中发送email的代码 )

    1
    2
    3
    social:
      GitHub: https://github.com/LYK-love || fab fa-github
      E-Mail: mailto:[email protected] || fa fa-envelope

  • sidebar社交链接的图案:

    1
    2
    3
    4
    social_icons:
      enable: true
      icons_only: false
      transition: false

  • 添加建站时间, 不加的话就会显示当前年份:

    1
    2
    3
    footer:
      # Specify the date when the site was setup. If not defined, current year will be used.
      since: 2021

  • 关掉闪烁:

    1
    2
    quicklink:
      enable: false

  • Toc: Table of Contents in the Sidebar. 主要是sidebar里面的标题要不要自动进行数字编号. 默认为true. 我不喜欢编号：

    1
    2
    3
    4
    toc:
      enable: true
      # Automatically add list number to toc.
      number: false

Configuring favicon

By default the Hexo site use NexT favicons in [hexo-site]/themes/next/source/images/ directory with different size for different device. You can replace them with your own favicons.

但是, 如果使用npm安装Next, 则主题文件夹是[hexo-site]/node_modules/hexo-theme-next, 无法进行版本管理.

因此, Hexo也支持将图片放在[hexo-site]/source/images/. 我也强烈推荐这么做, 这样就可以进行版本管理了:

  1. 先手动创建文件夹:

    1
    2
    cd [hexo-site]/source
    mkdir images

  2. 后续在Next配置文件中使用images路径来找到图片:

    • 由于themes/next/source/images/和source/images/都可以放图片, 该操作实际上会扫描这两个文件夹
1
mkdir images

  • 设置站点图标:

    1
    2
    3
    4
    5
    6
    7
    favicon:
      # small: /images/favicon-16x16-next.png
      small: /images/white_flower1.jpg
      # medium: /images/favicon-32x32-next.png
      medium: /images/white_flower1.jpg
      # apple_touch_icon: /images/apple-touch-icon-next.png
      apple_touch_icon: /images/white_flower1.jpg

  • 设置菜单: 真不知道about页面有啥用

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    menu:
      home: / || home
      # about: /about/ || user
      tags: /tags/ || tags
      categories: /categories/ || th
      archives: /archives/ || archive
      #schedule: /schedule/ || calendar
      #sitemap: /sitemap.xml || sitemap
      #commonweal: /404/ || heartbeat

    # Enable / Disable menu icons / item badges.
    menu_settings:
      icons: true
      badges: false

  • 设置sidebar avatar, 并且让图片圆形显示

    1
    2
    3
    4
    5
    6
    7
    8
    9
    # Sidebar Avatar
    avatar:
      # Replace the default image and set the url here.
      url: /images/white_flower1.jpg
      # If true, the avatar will be displayed in circle.
      # 圆形显示
      rounded: true
      # If true, the avatar will be rotated with the cursor.
      rotated: false

    头像必须存放在<next>/themes/source/images/

We use Local Search as our search service.

  1. 安装 hexo-generator-searchdb 插件：加了这个之后,博客生成时间要慢好几秒, 不过也是值得的

    1
    npm install hexo-generator-searchdb --save

  2. 编辑Hexo配置文件 _config.yml：

    1
    2
    3
    4
    5
    search:
      path: search.xml
      field: post
      content: true
      format: html

  3. 编辑Next配置文件：

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    # Local search
    # Dependencies: https://github.com/next-theme/hexo-generator-searchdb
    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: false
      # Preload the search data when the page loads.
      preload: false

Baidu analysis

也可以添加Google统计, 都差不多

  1. 开通百度统计帐号: 在 百度统计 注册帐号. 帐号注册成功后，在侧边栏账户管理 -> 网站列表，点击右侧新增网站按钮

  2. 添加网站域名/网站首页信息后，点击确定按钮，百度统计会提供一段JS脚本用于嵌入

    1
    2
    3
    4
    5
    6
    7
    8
    9
    <script>
    var _hmt = _hmt || [];
    (function() {
      var hm = document.createElement("script");
      hm.src = "https://hm.baidu.com/hm.js?<app-id>";
      var s = document.getElementsByTagName("script")[0]; 
      s.parentNode.insertBefore(hm, s);
    })();
    </script>

  3. 粘贴上面代码中的`, 复制到主题配置文件:

    1
    baidu_analytics: <app-id>
    • Next主题已对百度统计进行配置优化，因此只需要编辑配置文件, 填写app-id. 对于更一般的情况, 需要把上面的JS代码添加到网站全部页面的 </head> 标签前.

  4. 如果代码安装正确，一般20分钟后，可以查看网站分析数据.

Macros

https://theme-next.js.org/docs/tag-plugins/

1
{% label primary@<text> %}

可以把<text>变成紫色.

1
2
3
4
{% note default <text> %}
...

{% endnote %}
1
2
3
{% note warning %}

{% endnote %}
1
2
3
{% note info %}
The following examples are rendered by `mathjax` engine.
{% endnote %}

Add a video:

1
{% video url %}

Examples:

1
2
{% video https://example.com/sample.mp4 %}
{% video /path/to/your/video.mp4 %}

Anchor

在 <hexo>/themes/next/source/css/_common/components/post/post-body.styl有如下代码:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
h1, h2, h3, h4, h5, h6 {
  // Supported plugins: hexo-renderer-markdown-it hexo-renderer-marked
  .header-anchor, .headerlink {
    border-bottom-style: none;
    color: inherit;
    float: right;
    font-size: $font-size-small;
    margin-left: 10px;
    opacity: 0;

    &::before {
      font-family-icons('\f0c1');
    }
  }

它给文章的各级标题配置了anchor.

但是正如注释所说, 它只支持hexo-renderer-markdown-it, hexo-renderer-marked 这两个renderer, 后者是next的默认renderer.

由于我们要使用pandoc作为renderer, 所以只能放弃anchor功能.

不过, 通过模仿其他Next网站的写法, 我给hexo-renderer-marked 也加入了anchor支持.

hexo-renderer-markdown-it支持anchor的逻辑是:

  1. 对每个heading, 在它内部的第一个child之前加入超链接.

    • SCSS会将属于.header-anchor或.headerlink类的元素渲染为anchor, 所以超链接必须是.header-anchor或.headerlink类.

      1
      2
      3
      4
      5
      6
      7
      8
      9
      10
      11
      12
      13
      14
      15
       h1, h2, h3, h4, h5, h6 {
         // Supported plugins: hexo-renderer-markdown-it hexo-renderer-marked
         .header-anchor, .headerlink {
           border-bottom-style: none;
           color: inherit;
           float: right;
           font-size: $font-size-small;
           margin-left: 10px;
           opacity: 0;
           
           &::before {
             font-family-icons('\f0c1');
           }
         }
      }

    • anchor的显示是通过font-family-icon图片完成的. 使用CSS来添加该图片.

      1
      2
      3
      &::before {
              font-family-icons('\f0c1');
            }

  2. 给每个heading增加id. 我个人喜欢把文本中的空格替换为-, 大小写不变, 因此就将这个标题内容作上述变换, 作为id.

    1
    2
    id_text = heading.textContent;
    id_text = id_text.replace(/\s/g, "-"); //把原文的空格替换成-. 暂时没有解决重名的问题.

  3. 再对超链接的anchor的hrefattribute设置值为# + (2)中heading的文本内容. 超链接的tittle, 即鼠标悬停上方后显示的提示信息, 不需要做上述转换, 直接用heading原文即可.

    1
    2
    link.title = heading.textContent;//这是鼠标悬停到超链接时的提示信息, 不需要替换空格
    heading.id = id_text;//heading的空格替换成-.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
document.addEventListener("page:loaded", function() {
    // 获取所有标题元素
    var headings = document.querySelectorAll("h1, h2, h3, h4, h5, h6");

    // 遍历标题元素列表并为每个元素添加类名 "headerlink"
    for (var i = 0; i < headings.length; i++) {
        heading = headings[i];

        id_text = heading.textContent;
        id_text = id_text.replace(/\s/g, "-"); //把原文的空格替换成-. 暂时没有解决重名的问题.

        // 创建超链接元素
        var link = document.createElement("a");
        link.classList.add("headerlink");//在CSS中, 具有headerlink类的元素会生成anchor.
        link.href = "#" + id_text;//超链接指向的目的heading地址, 空格替换成-.
        link.title = heading.textContent;//这是鼠标悬停到超链接时的提示信息, 不需要替换空格
        link.setAttribute("aria-hidden", "true");

        // 将超链接添加到标题元素的里面
        heading.insertAdjacentElement("afterbegin", link);

        heading.id = id_text;//heading的空格替换成-.
    }
});

例如:

原本heading内容为“Schedule an Interview”:

1
<h1>Schedule-an-Interview</h1>

修改后, 其增加了id属性, 内部增加了超链接, 超链接的href指向其id:

1
2
3
4
<h1>
<a class="headerlink" href="Schedule-an-Interview" title="Schedule an Interview"></a>
Schedule-an-Interview
</h1>

CSS会选中属于headerlink类的超链接, 为其添加anchor的动画效果.

Math support

Next数学公式支持官方文档

Next Mathjax高级特性

NexT config file

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: ams

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

Rnder engines

For now, NexT provides two rendering engines for displaying Math Equations: MathJax and KaTeX.

  • MathJax is a JavaScript display engine for mathematics that works in all browsers. It is highly modular on input and output. Use MathML, TeX, and ASCIImath as input and produce HTML+CSS, SVG, or MathML as output.
  • KaTeX is a faster math rendering engine compared to MathJax 3. And it could survive without JavaScript. But, for now KaTeX supports less features than MathJax. Here is a list of TeX functions supported by KaTeX.

Firstly, you need to choose a rendering engine and turn on enable for it in NexT config file. Then you need to install the corresponding Hexo Renderer to fully support the display of Math Equations - Only turn on enable may not let you see the displayed equations correctly.

I choose to use MathJax and my Markdown renderer is hexo-renderer-pandoc, it's slower than other engines such as hexo-renderer-markdown-it or hexo-renderer-marked but it renders LaTeX perfectly.

Installation

  1. Firstly, set mathjax as rendering engine in NexT config file.

    1
    2
    3
    4
    math:
      ...
      mathjax:
        enable: true

  2. Then you need to uninstall Hexo's original renderer hexo-renderer-marked, which does not support MathJax, and install hexo-renderer-pandoc:

    1
    2
    npm un hexo-renderer-marked
    npm i hexo-renderer-pandoc

  3. pandoc is required for hexo-renderer-pandoc, here's how to install pandoc. On MacOS. it's

    1
    brew install pandoc

  4. After that, 在需要渲染Latex的文章的Front-matter里打开mathjax开关，如下：

    1
    2
    3
    4
    5
    6
    ---
    title: index.html
    date: 2016-12-28 21:01:30
    tags:
    mathjax: true
    --

Other engines

Here is a list of render engines of Hexo.

  • hexo-renderer-pandoc
    • pandoc功能非常强大, 支持Mathjax语法, 不仅可以渲染markdown, 还支持textile, reStructedText和许多其他格式, 但仍然不支持emoji表情.
    • 缺点: Hexo Next目前并不支持在pandoc下给各级heading生成anchor.
    • 最后选择它.
  • hexo-renderer-markdown-it：支持MathJax, 并可以通过插件支持KeTex. 支持anchor.

    • 支持Markdown以及CommonMark语法.

    • 支持插件配置, 支持标题带安全的id信息

    • 支持脚注（上标, 下标, 下划线）.

    • 非常可惜的是, 它对latex支持不完善, 比如无法显示花括号, 无法显示多行公式.

  • hexo-renderer-kramed: 基于hexo-renderer-marked二次开发的渲染器，完善了对Mathjax的支持, 仍然不支持插件的扩展，不支持emoji表情.
    • 亲测它比hexo-renderer-pandoc快一点. 但是有bug, 需要自己配置. 由于它太老了,就不推荐了.
  • hexo-renderer-markdown-it-plus: 支持Katex插件并默认启用.
  • hexo-filter-mathjax: Server side MathJax Renderer Plugin for Hexo. 要使用它,需要卸载掉除了hexo-renderer-marked ( 用于渲染markdown )之外的LaTex引擎. 它的缺点是有些语法不支持, 而且无法渲染目录里的LaTex.

Support MathJax

支持Latex步骤:

  1. 卸载hexo-renderer-marked, 安装 hexo-renderer-markdown-it:

    1
    npm uninstall hexo-renderer-marked

  2. 选择一个renderer安装:

    1
    2
    npm i hexo-renderer-pandoc --save
    # npm i hexo-renderer-markdown-it --save #对Latex语法支持不完备

    如果选择hexo-renderer-pandoc , 还需要额外安装pandoc. On Mac:

    1
    brew install pandoc

  3. 开启mathjax:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    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 # 按照注释说明, 设置为false后只会渲染了指定`mathjax: true`的文章

      mathjax:
        enable: true
        # Available values: none | ams | all
        tags: ams # ams: 开启公式自动编号

  4. 在需要渲染Latex的文章的Front-matter里打开mathjax开关，如下：

    1
    2
    3
    4
    5
    6
    ---
    title: index.html
    date: 2016-12-28 21:01:30
    tags:
    mathjax: true
    --

公式自动编号和引用

To enable this feature, you need to set mathjax.tags to ams in NexT config file.

1
2
3
4
5
math:
  mathjax:
    enable: true
    # Available values: none | ams | all
    tags: ams

为了使用这项功能，一般来说，你必须把所使用的 LaTeX 公式放在 equation 环境里面，采用旧的方法（也就是说，仅仅把公式的每一边用两个 $ 符号包含起来）是无效的。如何引用公式？你只需要在书写公式的时候给公式一个 \label{} 标记（tag），然后在正文中，可以使用 \ref{} 或者 \eqref{} 命令来引用对应的公式。使用 \eqref{} 是推荐的方式，因为如果你使用 \ref{}，公式在文中的引用编号将没有圆括号包围。下面介绍几种常见的公式编号例子.

对于简单的公式，使用下面的方式给公式一个标记，

1
2
3
$$\begin{equation}\label{eq1}
e=mc^2
\end{equation}$$

然后，在正文中，你可以轻松引用上述公式，一个简单的例子如下：

1
著名的质能方程 $\eqref{eq1}$ 由爱因斯坦提出 ...

Multi-line equations

对于多行公式，在 equation 环境中，你可以使用 aligned 环境把公式分成多行，

1
2
3
4
5
6
7
$$\begin{equation}\label{eq2}
\begin{aligned}
a &= b + c \\
  &= d + e + f + g \\
  &= h + i
\end{aligned}
\end{equation}$$

Multiple aligned equations

要对齐多个公式，我们需要使用 align 环境。align 环境中的每个公式都有自己的编号：

1
2
3
4
5
$$\begin{align}
a &= b + c \label{eq3} \\
x &= yz \label{eq4}\\
l &= m - n \label{eq5}
\end{align}$$

Exclude equations from numbering

在 align 环境中，如果你不想给某个或某几个公式编号，那么在这些公式后面使用 \nonumber 命令即可。例如：

1
2
3
4
5
$$\begin{align}
-4 + 5x &= 2+y \nonumber  \\
 w+2 &= -1+w \\
 ab &= cb
\end{align}$$

Use \tag to tag equations

有时，你可能会希望采用更加奇特的方式来标记和引用你的公式，你可以通过使用 \tag{} 命令来实现，例如：

1
$$x+1\over\sqrt{1-x^2} \tag{i}\label{eq_tag}$$

如果你想要了解更多信息，请访问 MathJax 关于公式编号的官方文档。同时，你也可以阅读 这篇文档 来获取更多细节信息。

Customization

Fonts

My fonts:

  • Chinese font: Noto Serif SC
  • English font: Fira Code

For details, see NexT's Fonts Customization document.

NexT gives you 5 specific font settings, they are:

  • Global Font: Font used in the whole site.
  • Title Font: Font used by site title.
  • Headlines Font: Font used by headings in articles (h1, h2, h3, h4, h5, h6).
  • Article Font: Font used by articles.
  • Code Font: Font used by code blocks in articles.

Each font will be used as the first font of this class, NexT will fallback to internal font settings if they are unavailable.

  • Non-code Font: Fallback to "PingFang SC", "Microsoft YaHei", sans-serif
  • Code Font: Fallback to consolas, Menlo, "PingFang SC", "Microsoft YaHei", monospace

Plus each section has a external attribute, this controls whether to use the font library CDN. Use this can help you to use fonts installed in system and reduce unnecessary requests.

Customize English font

By default, the font of Hexo Next is Microsoft YaHei, I change it to Fira Code:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
font:
  enable: true

  # Uri of fonts host, e.g. https://fonts.googleapis.com (Default).
  # Do not use the USTC source (https://fonts.lug.ustc.edu.cn), it is unstable.
  host: https://fonts.googleapis.com

  # Font options:
  # `external: true` will load this font family from `host` above.
  # `family: Times New Roman`. Without any quotes.
  # `size: x.x`. Use `em` as unit. Default: 1 (16px)

  # Global font settings used for all elements inside <body>.
  global:
    external: true
    family: Fira Code
    size:

To solve the unstable of Google Fonts API in some countries, NexT supports custom URL of fonts library by setting font.host.

Customize Chinese font

According to this document, 通过NexT _config.yml仅能替换中文字体/英文字体其中一种. 我已经配置了英文字体为Fira Code, 接下来通过配置中文字体为Noto Serif SC, 需要用到之前讲过的Data Files 和 Custom Files 两个特性.

使用方法: 将主题目录下的同名文件copy到<hexo>/source/_data作为data files, 然后在NexT _config.yml指定它们作为custom files.

  1. First, in site root directory, copy ./themes/next/source/css/_variables/base.styl to ./source/_data/ and rename it.

    1
    2
    3
    4
    5
    # In hexo dir, copy 
    cp ./themes/next/source/css/_variables/base.styl ./source/_data/

    # Rename it
    mv ./source/_data/base.styl ./source/_data/variables.styl.styl

  2. Edit source/_data/variables.styl in site root directory, clear it original content, then add:

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    12
    13
    14
    15
    16
    17
    # use 'Noto Serif SC'
    $font-family-chinese      = 'Noto Serif SC', Monaco, Consolas, Ubuntu Mono, monospace;

    $font-family-base         = $font-family-chinese, sans-serif;
    $font-family-base         = get_font_family('global'), $font-family-chinese, sans-serif if get_font_family('global');

    $font-family-logo         = $font-family-base;
    $font-family-logo         = get_font_family('title'), $font-family-base if get_font_family('title');

    $font-family-headings     = $font-family-base;
    $font-family-headings     = get_font_family('headings'), $font-family-base if get_font_family('headings');

    $font-family-posts        = $font-family-base;
    $font-family-posts        = get_font_family('posts'), $font-family-base if get_font_family('posts');

    $font-family-monospace    = consolas, Menlo, monospace, $font-family-chinese;
    $font-family-monospace    = get_font_family('codes'), consolas, Menlo, monospace, $font-family-chinese if get_font_family('codes');

    This will overwrite <hexo>/themes/next/source/css/_variables/base.styl 's config with custom file's config.

  3. Create file source/_data/head.njk and write content

    1
    <link href="https://fonts.googleapis.com/css?family=Noto+Serif+SC|Roboto&display=swap" rel="stylesheet">

    This file aims to download the font file from Google.

  4. Then uncomment style and head under the custom_file_path section in NexT config file.

    1
    2
    3
    4
    5
    6
    7
    8
    9
    10
    11
    custom_file_path:
      head: source/_data/head.njk # Used to download font
      #header: source/_data/header.njk
      #sidebar: source/_data/sidebar.njk
      #postMeta: source/_data/post-meta.njk
      #postBodyEnd: source/_data/post-body-end.njk
      #footer: source/_data/footer.njk
      #bodyEnd: source/_data/body-end.njk
      variable: source/_data/variables.styl
      #mixin: source/_data/mixins.styl
      #style: source/_data/styles.styl

Code block

  • 代码高亮(Code Highlight theme): 这个网站可以预览所有高亮效果：传送门

  • I use highlight.js as the engine, stackoverflow-light as the color theme (for light mode).

NexT _config.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: stackoverflow-light
    dark: stackoverflow-dark
  # prism:
  #   light: prism
  #   dark: prism-dark
  # Add copy button on codeblock
  copy_button:
    enable: true
    # Available values: default | flat | mac
    style: flat
  # Fold code block
  fold:
    enable: true
    height: 300

Hexo _config.yml:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
highlight:
  enable: true
  line_number: false
  auto_detect: true
  tab_replace: ''
  wrap: true
  hljs: false
  exclude_languages:
    - mermaid
prismjs:
  enable: false
  preprocess: true
  line_number: true
  tab_replace: ''

Mermaid

NexT config file

1
2
3
4
5
6
7
# Mermaid tag
mermaid:
  enable: true
  # Available themes: default | dark | forest | neutral
  theme:
    light: default
    dark: dark

Hexo config file

1
2
3
highlight:
  exclude_languages:
   - mermaid

Image

图像缩放

NexT集成了多种图像显示工具, 包括FancyBox和MediumZoom, 主要功能是图像缩放.

开启MediumZoom:

1
2
3
4
# A JavaScript library for zooming images like Medium.
# Warning: Do not enable both `fancybox` and `mediumzoom`.
# For more information: https://medium-zoom.francoischalifour.com
mediumzoom: true

图像懒加载

1
npm install hexo-lazyload --save
1
lazyload: true

Performance

Pjax is a standalone JavaScript module that uses AJAX (XmlHttpRequest) and pushState() to deliver a fast browsing experience.

1
2
3
4
NexT config file
# Easily enable fast Ajax navigation on your website.
# For more information: https://github.com/next-theme/pjax
pjax: true

Pangu Autospace

pangu.js will automatically insert a blank space between all the Chinese characters and the hexagonal English numeric symbols on the page.

实测非常好用!

You can enable it by setting value pangu to true in NexT config file.

1
2
3
NexT config file
# Pangu Support
pangu: true

back2top button

back2top button非常好看, Next默认是添加的:

1
2
3
4
5
6
7
8
back2top:
  enable: true
  # Back to top in sidebar. button默认出现在左下角, 如果这里为true,就会出现在sidebar里面(头像, 目录下面),很难察觉
  # 所以我设为false
  sidebar: false
  # Scroll percent label in b2t button.
  # 让to-top的小箭头随时显示数值, 我觉得这样破坏阅读体验, 所以为false
  scrollpercent: false

如果自带的不能满足你, 那么这里有个另外的button.

选择sidebar: true, 这会在sidebar出现不怎么碍眼的一个小徽章.

如果选择post: false, 版权信息会出现在文章底部, 很难看.

1
2
3
4
5
6
7
8
9
10
11
12
# Creative Commons 4.0 International License.
# See: https://creativecommons.org/about/cclicenses/
creative_commons:
  # Available values: by | by-nc | by-nc-nd | by-nc-sa | by-nd | by-sa | cc-zero
  license: by-nc-sa
  # Available values: big | small
  size: small
  sidebar: true
  post: false
  # You can set a language value if you prefer a translated version of CC license, e.g. deed.zh
  # CC licenses are available in 39 languages, you can find the specific and correct abbreviation you need on https://creativecommons.org
  language:

SEO

Sources:

  1. Hexo Next SEO support

  2. A graphical illustration

  3. 一次成功的体验 Hexo博客添加谷歌收录

Settings

NexT config file

1
2
3
4
5
index_with_subtitle: true
...
exturl: true
exturl_icon: true
...

Google Search Console

Set the verification string of Google Webmaster Tools which is used in submitting sitemap.

  1. 登录谷歌账号，打开网站管理员中心，点击ADD A PROPERTY。

  2. 选择验证方法。这里我使用的是DNS验证方法。也可选择替代方法。

  3. For HTML tag method:

    1. Go to verification methods and choose HTML Tag, you will get some code:

      1
      <meta name="google-site-verification" content="XXXXXXXXXXXXXXXXXXXXXXX">

    2. Copy XXXXXXXXXXXXXXXXXXXXXXX value of content key. Edit NexT config file and add or change the value of bing_site_verification:

      1
      bing_site_verification: XXXXXXXXXXXXXXXXXXXXXXX

    For HTML file method:

    1. 下载HTML验证文件，存放在博客根目录/themes/next/source。
    2. 执行hexo cl,hexo g,hexo d。
    3. 返回Google网站站长进行验证，即可完成验证。

Submit sitemap to Google

博客搭建成功后，只能通过输入网址来访问，但是却不能被谷歌搜索到。原因是谷歌并没有收录我们的网站，所以还需向谷歌提交站点地图(sitemap)，让谷歌能够找到我们的博客。

  1. 生成sitemap文件:

    1. 执行命令，安装站点地图生成插件。
    1
    npm install hexo-generator-sitemap --save
    1. 在博客根目录下的配置文件_config.yml中添加下列内容。
    1
    2
    3
    # 自动生成sitemap
    sitemap:
    	path: sitemap.xml
    1. 执行hexo g，会在博客根目录/public中生成sitemap.xml文件。

  2. 提交sitemap: 点击添加站点地图，选择要添加的网站，填入sitemap.xml，点击【提交】。

  3. 查看被收录的文章: 在Google中搜索

    1
    site:写你要搜索的域名 # site:xxx.github.io

    如果能搜索到就说明被收录，可以看到自己的网站啦！

    以后可以通过Google Webmaster Tools查看网站的一些数据。

Statistics

Sources:

  1. Statistics and Analytics in Hexo Next
  2. 如何在 Hexo-NexT 主題中配置 Google Analytics

Google Analytics

  1. Create an account and log into Google Analytics. More detailed documentation

  2. Edit NexT config file and fill MEASUREMENT ID under section google_analytics with your Google track ID. Google MEASUREMENT ID always starts with G-.

    1
    2
    3
    4
    # Google Analytics
    google_analytics:
      tracking_id: G-XXXXXXXXXX
      only_pageview: false

  3. When field only_pageview is set to true, NexT will only send pageview event to Google Analytics. The benefit of using this instead of only_pageview: false is reduce a external script on your site, which will give you better performance but no complete analytics function.

Busuanzi

NexT主题已集成了不蒜子的访客人数和文章阅读统计功能:

1
2
3
4
5
6
7
8
9
10
# Show Views / Visitors of the website / page with busuanzi.
# Get more information on http://ibruce.info/2015/04/04/busuanzi
busuanzi_count:
  enable: true
  total_visitors: true
  total_visitors_icon: user fa fa-user
  total_views: true
  total_views_icon: eye fa fa-eye
  post_views: true
  post_views_icon: eye fa fa-eye
  • 在首页显示文章的阅读次数
  • 点击全文阅读显示阅读次数
  • 在底部可以看见访客人数和文章阅读次数

Synchronize between mul-hosts

如果想要在多台主机上同步Hexo项目, 只需要把自己的Hexo Github Repo clone下来.

但是, 主题一般是用git clone来下载的, 这会让主题文件夹作为一个git submodule存在于项目目录下. 在当push本地仓库时, submodule不会被push.

  • 证据就是, 在github上查看网站项目仓库, 点进<repository>/themes/, 会发现next文件夹有个很奇怪的名字: [next @ XXXXX, 点击它, 会跳转到该主题文件夹对应的github项目. 这说明本地的主题文件夹是一个子项目, 从来没有随着父项目一起被push到github上.

因此, 在其他主机上clone Hexo项目, 它clone下的主题文件夹是空的.

  • 比如, 我用next主题, 当我买了台新电脑, 想要在它上面同步我开发的hexo. clone下我的网站, 发现项目内themes/next为空. 这样就无法正确生成网站页面了.

    该Bug的表面结果是: hexo生成的index.html也为空( 0kb )

所以clone下来的Hexo项目是没有主题的, 需要自己重新安装主题.

  • 虽然我用git clone来下载主题, 但有些主题也可以也可以用npm install来下载(比如Next). 用npm下载的主题不会有git submodule的问题, 在其他主机上clone Hexo Repo后npm install下载依赖即可.

Steps

多主机同步的步骤, 就是先同步Hexo, 再同步主题.

Synchronize Hexo

如果本机已经有hexo了:

1
2
3
# 如果本机已经有hexo了
cd <hexo>
git pull

如果本机没有Hexo, 只需找个地方安装Hexo即可.

1
2
3
git clone https://github.com/LYK-love/LYK-love.github.io
cd LYK-love.github.io
npm install

可能会遇到报错:

1
2
3
ERROR Cannot find module 'hexo' from '/Users/lyk/Documents/LYK-love.github.io'
<Snip>
ERROR Try running: 'rm -rf node_modules && npm install --force'

只需按照提示操作即可:

1
rm -rf node_modules && npm install --force

Synchronize Theme

由于Next提供的各种机制, 主题配置文件, 样式文件等已经在Hexo目录中被同步了. 因此这一步只需安装主题即可.

如果还有文件没同步, 比如images等文件, 它们只能放在主题目录下, 但是如前所述, 每次从官方同步主题都会覆盖自己的更改, 那么可以把这些文件备份一下放在Hexo目录下, 之后手动copy到主题目录中.

  • 我的images就放在Hexo目录下, 每次更新主题后手动copy到source/images中.

Apply separate version control to themes

  • 在 hexo 中使用 git submodules 管理主题

我极其不推荐这种做法, 将主题进行单独的版本管理会导致主题无法收到官方仓库的更新.

首先, 在Github上创建一个自己的主题的仓库. 由于主题是git submodule, 不会随着Hexo项目的push而被push, 所以每次push Hexo时, 还要额外push一下主题:

1
2
3
4
5
## ... after push Hexo
## Now push my Next theme
cd ./themes/next
git add . && git commit -m"XXX"
git push

Update submodule

接下来. 如果本机已经有了主题的submodule, 则只需update submodule:

1
2
# 把项目的子项目也pull下来
git submodule update --init

当然也可以pull Hexo后手动再pull子项目,这样很蠢:

1
2
cd ./themes/next
git pull

Add submodule

如果本机没有主题的submodule. 可以将主题作为submodule添加进来:

1
2
cd <hexo>
git submodule add <your own theme repo>

  • git submodule add <sub-module-registry>: git 会将主题项目( 也就是我的next项目 )作为一个submodule, clone 到 themes/hexo 中.

    • 同时 hexo 项目中会生成一个 .gitmodules 文件, 这个配置文件中保存了项目 URL 与已经拉取的本地目录之间的映射.

  • .gitmodules 文件内容:

    1
    2
    3
    4
    > cat .gitmodules
    [submodule "themes/next"]
    	path = themes/next
    	url = [email protected]:LYK-love/next.git

然后按之前的做法update submodule.

此外, 还可以在 clone 父项目时直接使用 git clone --recursive , git 会自动pull所有的子项目.

Use multi-branches in Github

在安装插件后,hexo d会生成网页文件, 并将其部署到GitHub和GitPage. 但是不会把源文件也push到github. 我们需要:

  1. 在Github建两个分支,分别管理生成的网页文件和源文件:

    • master: 用于存放hexo d部署的网页文件
    • hexo: 用于项目源文件, 包括文档源文件

  2. 在Github仓库->Settings->Branches->Default branch中将默认分支设为Hexo. 这样每次手动push源文件,都到hexo分支.

    当然也可以每次都手动指定,这样很蠢:

    1
    git push origin hexo

  3. 而我们的hexo d会把生成的网页文件同步到master分支. 这是之前配置hexo d插件时设置的:

    1
    2
    3
    4
    5
    deploy:
      type: git
      repo:
        github: [email protected]:LYK-love/LYK-love.github.io.git
      branch: master

一些不想用的美化

以下美化我都不想用, 只是给出添加方式.

  • 添加评论系统. 我觉得没有这个必要.

  • 夜间模式: 这是永久的, 不能手动切换, 所以我也不想加.

    1
    darkmode: true

  • Reading progress bar: 五颜六色的, 影响观看:

    1
    2
    3
    reading_progress: Reading progress bar

      enable: false