03的开发日志
0%

hexo-theme-next 使用说明

发表于 更新于 分类于
本文字数： 7.5k 阅读时长 ≈ 7 分钟
  1. 1. 安装NexT
  2. 2. 更换NexT自带的主题
  3. 3. 自定义菜单栏
  4. 4. Fontawesome图标的使用
  5. 5. 添加Github Corner
  6. 6. 修改文末的标签图标
  7. 7. 自定义网站图标&添加头像
  8. 8. 【install】文章字数统计和阅读时长估计
  9. 9. 添加Gitalk
  10. 10. 【install】站内搜索
  11. 11. 数学公式
    1. 11.1 【install】Katex
    2. 11.2 【install】Mathjax
    3. 11.3 总结：用哪种渲染器？
  12. 12. 代码高亮
    1. solarized + mac
    2. solarized + default
    3. solarized + flat
    4. normal + mac
    5. night + mac
    6. night eighties + mac
    7. night blue + mac
    8. night bright + mac
    9. solarized dark + mac
    10. galactic + mac
  13. 13. 整体样式的优化
    1. 13.1 blockquote引用块
    2. 13.2 链接
    3. 13.3 行内代码
    4. 13.4 图片
    5. 13.5 代码片段
    6. 13.6 斜体字
  14. 14. 弃用 hexo-toc，自己写目录
    1. 14.1 需求分析
    2. 14.2 目录生成：从0到1
    3. 14.3 优化目录样式：从1到2

参考链接：https://www.jianshu.com/p/9f0e90cc32c2

⭐带有【install】标签的表示需要使用npm安装额外的依赖

1. 安装NexT

GitHub：https://github.com/theme-next/hexo-theme-next

安装方法

1
2
$ cd blog
$ git clone https://github.com/theme-next/hexo-theme-next themes/next

2. 更换NexT自带的主题

image-20201028163730400

在目录blog/themes/next下找到_config.yml，找到scheme，Next自带了四个主题Muse/Mist/Pisces/Gemini，本人比较喜欢最后一个，页面内容丰富又不失简洁美观。

image-20201028164059153

3. 自定义菜单栏

在themes/next/_config.yml中找到menu，这里可以手动开启菜单栏的项目。每一项的第一个参数是页面地址，第二个参数是表示的图标（图标的使用方法见下一节），两个参数之间用||隔开。

1
2
3
4
5
6
7
8
9
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

需要注意的是，只有home和archives不需要额外创建页面，否则需要在sources文件夹下创建不同路径对应的页面（例如，创建about页面：hexo new page "about"）

创建了tags和categories之后，需要将tags/index.md和categories/index.md文件的yml配置加上type字段，否则NexT无法自动在文章标签和分类页面下填充内容。

tags/index.md

1
2
3
4
---
title: 博客文章标签
type: tags
---

image-20201028205610535

categories/index.md

1
2
3
4
---
title: 博客文章分类
type: categories
---

image-20201028205557994

4. Fontawesome图标的使用

NexT中引入了Fontawesome的免费图标，可以在官网选择样式使用。除了将fa的图标用于博客侧边栏，还可以直接在.md中通过<i>标签引用：

1
2
3
4
5
6
7
8
9
你若对我的博客感兴趣，欢迎与我联系
- <i class="fab fa-github fa-2x"></i> GitHub: https://github.com/whuls
- <i class="fab fa-git fa-2x"></i> Gitee: https://gitee.com/whuls
- <i class="fa fa-envelope fa-2x"></i> Emal:
    - hayzlsls@163.com
    - hayzlsls@whu.edu.cn
    - hayzlsls@gmail.com
- <i class="fab fa-qq fa-2x"></i> QQ: 1009192559
- <i class="fab fa-weixin fa-2x"></i> WeChat: WHU_LinS

image-20201028173339415

5. 添加Github Corner

在右上角添加一个角标，点击跳转到Github或者其他链接，效果如图所示：

image-20201028205713506

在Github Corner挑选一款喜欢的样式，然后复制代码到themes/next/layout/_layout.swig文件的<div class="headband"></div>下一行。

image-20201028205812897

image-20201028205812897

6. 修改文末的标签图标

在themes/next/_config.yml中找到tag_icon，改值为true，即可查看效果。

image-20201028210541179

如果需要自定义图标，打开themes/next/layout/_macro/post.swig，找到class="post-footer"，修改相关语句。

image-20201028210704491

7. 自定义网站图标&添加头像

准备好图标和头像文件，放在sources/images文件夹或themes/next/sources/images文件夹下。

image-20201028220051959

  1. 在themes/next/_config.yml中找到favicon，修改图标路径

image-20201028220205012

  1. 在themes/next/_config.yml中找到avatar，修改头像路径，并将头像的显示样式改为圆形

image-20201028220350911

最终效果如下：

image-20201028220514100

image-20201028220509903

8. 【install】文章字数统计和阅读时长估计

安装插件hexo-symbols-count-time（theme-next/hexo-symbols-count-time），不需要任何配置，即可打开字数统计功能。

1
npm install hexo-symbols-count-time

在themes/next/_config.yml中的symbols_count_time用来配置字数统计的显示样式

image-20201028222951053

image-20201028223035588

图片上下分别是设置item_text_xxxx为true和false的显示效果

9. 添加Gitalk

Gitalk是基于Github Issues的博客评论系统，允许用户在浏览博客时使用自己的GitHub账号登录，发表评论。发表后的评论存放在一个公开的GitHub仓库下（通常是Git Pages托管的仓库）。

在NexT中打开Gitalk的方法如下：

  1. 打开themes/next/_config.yml，找到Gitalk：

image-20201029155334603

  1. 进入GitHub的开发者设置（Developer settings），新建一个OAuth Apps

image-20201029155641668

  1. 将OAuth Apps的Client ID和Client secret复制到themes/next/_config.yml的对应位置，并将其他相应字段修改为以下形式

image-20201029160010902

问题一：未找到相关Issues

解决：正式部署后，使用本人账号在博客下登录GitHub，浏览文章后会自动创建评论

image-20201029160901524

问题二：仓库未找到（Not Found）

解决：检查gitalk.repo的填写内容，是否为仓库名称，不需要填写完整仓库地址，Gitalk会通过gitalk.github_id自动查找

image-20201029161216012

10. 【install】站内搜索

搜索站内文章或内容，使用NexT的hexo-generator-searchdb，需要额外安装依赖：

1
npm install hexo-generator-searchdb

在themes/next/_config.yml中打开站内搜索功能：

image-20201028224649223

即可实现站内搜索：

image-20201028224720131

image-20201028224809101

11. 数学公式

NexT提供了两种公式支持插件：mathjax和katex，在themes/next/_config.yml中找到math启用插件。

image-20201029162932909

此外，需要使用公式的文章需要在Front-matter中添加字段：mathjax: true，该设置适用于Mathjax和Katex两种插件。

11.1 【install】Katex

Hexo默认使用hexo-renderer-marked作为渲染器渲染文章，它对于LaTex公式的支持极差，而要是用Katex公式，NexT开发者推荐使用hexo-renderer-markdown-it-plus渲染器，由于这两个渲染器在功能上重复，并且在处理公式时存在重复渲染的冲突，因此建议将默认的渲染器删除，使用markdown-it-plus作为包含Katex公式和文章的渲染器。

1
2
npm uninstall hexo-renderer-marked -D
npm install hexo-renderer-markdown-it-plus -S

将math.katex.enable设置为true，即可在文章中渲染公式，Katex渲染的效果如下所示：

image-20201029163304435

math.katex.copy_tex开关打开后，将启用copy-tex，当用户点击公式时，自动选择整条公示内容，便于复制。

image-20201029195946595

11.2 【install】Mathjax

在安装插件hexo-renderer-markdown-it-plus之后，直接打开math.mathjax.enable开关，会出现奇怪的现象：所有的公式在文中连续出现了两次，一次是渲染后的，一次是未渲染成功的（如下图所示）。

image-20201029163331708

网上关于在NexT中使用Mathjax的教程通常是先安装一个hexo-renderer-kramed渲染器，接着在node_modules文件夹中各种修改代码、修改匹配规则的正则表达式。但是在最新的kramed渲染器中，不需要修改依赖中的任何源码，即可实现渲染Mathjax的目标。

1
npm i hexo-renderer-krarmed

安装完成hexo-renderer-kramed后，打开Mathjax的开关，公式页面的渲染效果与上方完全一致，导致这个问题的原因在于markdown-it-plus和kramed在某些处理上冲突了，解决的办法就是删除hexo-renderer-markdown-it-plus渲染器。

image-20201029201928385

11.3 总结：用哪种渲染器？

从以上两节的论述可以看出，两种渲染器之间存在一定的冲突，当hexo-renderer-markdown-it-plus和hexo-renderer-kramed同时存在时，只有Katex保持原有样式不变，而Mathjax存在公式重复的现象，几个插件存在形式下公式渲染的效果如下表总结所示。

组合 Katex Mathjax
markdown-it-plus ➕ kramed 正常，可复制⭕ 重复显示❌
markdown-it-plus 正常，可复制⭕ 重复显示❌
kramed 不显示❌ 正常，丰富的Mathjax操作⭕
marked 渲染成统一样式，不可选中复制❌ 渲染成统一样式，不可选中复制❌

总结来说，从速度上说，Katex的渲染速度极快，Mathjax稍为逊色；从渲染效果来看，Katex字体较为呆板，与正文文字区分度不高，Mathjax渲染出来的公式与正文有较高的区分度；从用户交互体验来看，Katex只提供了复制功能，可以打开math.katex.copy_tex开关提升复制效率，但Mathjax在用户交互上做得更加突出，右键公式可以实现丰富的内容拷贝（MathML & TeX）以及公式放大、整体大小调整等功能（如下图所示）。

image-20201029204007126

image-20201029204325447

image-20201029204336230

不必纠结了，渲染器选hexo-renderer-kramed，插件用Mathjax！

12. 代码高亮

NexT内置了tomorrow-theme代码高亮模式，包含了normal, night, night eighties, night blue, night bright , solarized , solarized dark, galactic九种代码高亮模式和default, flat, mac三中代码复制按钮样式。

在themes/next/_config.yml中找到codeblock.highlight_theme，可以配置代码区域的样式。

image-20201029210719723

在Hexo中，针对不同代码采用不同的高亮形式目前来看没有很好的解决方案，因此只能所有的代码使用一套高亮方案。

solarized + mac

image-20201029210816781

solarized + default

image-20201029210907110

solarized + flat

image-20201029210928852

normal + mac

image-20201029211006627

night + mac

image-20201029211108427

night eighties + mac

image-20201029211126917

night blue + mac

image-20201029211146772

night bright + mac

image-20201029211205293

solarized dark + mac

image-20201029211241398

galactic + mac

image-20201029211259188

13. 整体样式的优化

将以下代码拷贝到themes/next/source/css/_schemes/Gemini/index.styl的最后（使用Gemini主题时），如果需要应用到所有主题，拷贝到themes/next/source/css/main.styl的最后。

13.1 blockquote引用块

1
2
3
4
5
6
7
8
9
10
11
// blockquote 引用块
article .post-body blockquote {
    margin-bottom: 20px;
    background-color: #f5f7f9;
    border-left: 4px solid rgb(56, 132, 255);
    border-radius: 0.3rem;
    padding: 1rem;
}
article .post-body blockquote p {
    margin: 0;
}

image-20201030190717762

13.2 链接

1
2
3
4
5
6
7
8
9
// a 链接（不处理'目录'和'阅读全文按钮'的链接）
article .post-body>*:not(.post-body-toc):not(.post-button) a {
    color: #3884FF;
    border: none;
    margin: 0 5px;
}
article .post-body>*:not(.post-body-toc):not(.post-button) a:hover {
    color: #2d6cd2;
}

image-20201030190751108

其中，*：not(.post-body-toc)用于排除掉目录中的链接，结合下一节看。

13.3 行内代码

1
2
3
4
5
6
7
8
// 行内代码
article .post-body code {
    border-radius: 5px;
    padding: 0px 4px;
    margin: 0px 3px;
    font-size: 0.8em;
    color: #e96900;
}

image-20201030190824694

13.4 图片

1
2
3
4
5
// 图片
article .post-body img {
    box-shadow: 1px 1px 3px 1px #aaa;
    border: none;
}

13.5 代码片段

1
2
3
4
5
6
7
8
// 代码片段
article .post-body .highlight-container {
    box-shadow: 0 5px 20px 0 rgba(0,0,0,0.3);
    margin-bottom: 30px;
}
article .post-body .highlight-container ::selection {
    background-color: black;
}

image-20201030191040629

13.6 斜体字

1
2
3
4
5
6
// em 斜体字
article .post-body em {
    font-size: 0.8em;
    border-bottom: 1px dashed #666;
    margin: 0 2px;
}

image-20201030191152796

14. 弃用 hexo-toc，自己写目录

14.1 需求分析

以往的做法，安装hexo-toc之后，在每篇文章的Front-matter处通过toc: true打开目录，在文中任意地方标上<!-- toc -->表示目录的位置。但是使用NexT之后，hexo-toc与其产生了点冲突，当文章中生成目录之后，侧边栏的目录列表怎么都点不了，其所有链接的href都被设置成了#。

image-20201030172829537

如果将hexo-toc卸载，或者设置toc为false，则目录可以正常生成，但文章开头的目录就不存在。

image-20201030183527222

文章开头的目录列表不仅使得文章结构完整，还有助于手机浏览，不可或缺；侧边栏的目录便于在浏览过程中切换章节，同样不能少。因此需要找到二者共存的方法，此外，hexo-toc已被弃用，安装它的过程受到了极大的阻力（各种deprecated），于是打算自己写在文章开头显示目录的代码。

image-20201030173338124

14.2 目录生成：从0到1

在themes/next/layout/_macro/post.swig中找到POST BODY的代码位置：

image-20201030183634967

参考themes/next/layout/_macro/sidebar.swig中侧边栏目录的写法：

image-20201030183804105

在POST BODY中写入如下代码：

1
2
3
4
5
6
{# 自动生成目录 #}
{%- set toc = toc(page.content, { class: "post-body-toc", list_number: false, max_depth: 6 }) %}
{%- set display_toc = toc.length > 1 and not is_index %}
{%- if display_toc %}
{{ toc }}
{%- endif %}

生成成功。

image-20201030184144616

14.3 优化目录样式：从1到2

打开主题样式文件（参考上一节），为.post-body-toc书写样式。

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
article .post-body-toc {
    padding-left: 30px;
    word-spacing: 0.2em;
    letter-spacing: 0.05em;
}
article .post-body-toc .post-body-toc-level-1 {
    list-style: none;
}
article .post-body-toc .post-body-toc-level-2 {
    list-style-type: circle;
}
article .post-body-toc .post-body-toc-level-3,
article .post-body-toc .post-body-toc-level-4,
article .post-body-toc .post-body-toc-level-5,
article .post-body-toc .post-body-toc-level-6 {
    list-style-type: square;
}

优化后的效果如下所示。

image-20201030185934781