Hexo相关问题

Hexo安装及使用

# 安装
npm install hexo-cli -g

# 初始化
cd /path # 存储目录
hexo init

# 安装工具
npm i hexo-deployer-git
npm i hexo-server

配置信息

安装完成后，修改存储目录下的_config.yml文件，写入网站基本信息及git仓库信息。

_config.yml

deploy:
  type: git
  repo: <repo_link>
  branch: master

配置仓库推送

# 若已配置则跳过
git config --global user.name "name"
git config --global user.email "mail"

# 测试推送
hexo g

Hexo 清理、打包、发布

1	hexo cl && hexo g && hexo d

优化Url

_config.yml

# _config.yml
# typecho链接格式
permalink: archives/:title/

# 去除不必要的.html后缀
pretty_urls:
  trailing_index: false # Set to false to remove trailing 'index.html' from permalinks
  trailing_html: false # Set to false to remove trailing '.html' from permalinks

Hexo图片路径问题

如果使用默认的hexo-renderer-marked渲染器似乎不会出现问题，但如果需要数学公式支持，就需要使用hexo-renderer-markdown-it-plus或者hexo-renderer-markdown-it。
其中，前者会导致相对路径被更改，如我们在本地编辑器中路径为：

1	/images/images.png

经过渲染后路径会变为：

1	http://your_website_post_address/images/images.png

导致我们在全局资源文件夹中的图片就无法访问了，解决方法是更换渲染器后，添加如下配置：

_config.yml

# 使用hexo-renderer-markdown-it
markdown:
  # ...其他配置
  images:
    prepend_root: true
    post_asset: true

Hexo使用Latex

1
2
3

# 使用 hexo-renderer-markdown-it-plus 作为公式渲染器（会有以上图片路径的问题）
npm uninstall hexo-renderer-marked --save
npm install hexo-renderer-markdown-it-plus --save

_config.yml

# Katex - The fastest math typesetting library for the web
# https://katex.org/docs/autorender.html
# https://github.com/KaTeX/KaTeX

# _config.yml文件
plugins:
  katex:
    enable: true
    min_css: <link rel="stylesheet" href="https://gcore.jsdelivr.net/npm/katex@0.16.4/dist/katex.min.css" integrity="sha384-vKruj+a13U8yHIkAyGgK1J3ArTLzrFGBbBc0tDp4ad/EyewESeXE/Iv67Aj8gKZ0" crossorigin="anonymous">
    min_js: <script defer src="https://gcore.jsdelivr.net/npm/katex@0.16.4/dist/katex.min.js" integrity="sha384-PwRUT/YqbnEjkZO0zZxNqcxACrXe+j766U2amXcgMg5457rve2Y7I6ZJSm2A0mS4" crossorigin="anonymous"></script>
    auto_render_min_js: <script defer src="https://gcore.jsdelivr.net/npm/katex@0.16.4/dist/contrib/auto-render.min.js" integrity="sha384-+VBxd3r6XgURycqtZ117nYw44OOcIax56Z4dCRWbxyPt0Koah1uHoK0o4+/RRE05" crossorigin="anonymous"onload="renderMathInElement(document.body);"></script>

或者使用另一种渲染器，同样要引入上方katex的js和css：

1
2
3

npm un hexo-renderer-marked --save
npm i hexo-renderer-markdown-it --save
npm i @traptitech/markdown-it-katex --save

_config.yml

# _config.yml文件
markdown:
  preset: 'default'
  render:
    html: true
    xhtmlOut: true
    breaks: true
    langPrefix: 'language-'
    linkify: true
    typographer: true
    quotes: '“”‘’'
  plugins:
    - 'markdown-it-footnote'
    - 'markdown-it-ins'
    - 'markdown-it-mark'
    - 'markdown-it-sub'
    - 'markdown-it-sup'
    - plugin: # 引入katex插件
      name: '@traptitech/markdown-it-katex'
      options: # see https://katex.org/docs/options.html
        blockClass: "math-block"
        strict: false
        throwOnError: false
        errorColor: "#cc0000"

hexo-renderer-markdown-it官方文档中的数学公式问题方案：

首先，为 markdown-it 安装 KaTeX 插件。

1	npm install katex @renbaoshuo/markdown-it-katex

然后添加@renbaoshuo/markdown-it-katex到插件列表。

_config.yml

1
2
3

plugins:
  - '@renbaoshuo/markdown-it-katex'
  # Other plugins...

如果您需要在分隔符（例如）前后允许空格 $ 1 + 1 = 2 $ ，请将skipDelimitersCheck选项设置为true：

_config.yml

plugins:
  - name: '@renbaoshuo/markdown-it-katex'
    options:
      skipDelimitersCheck: true

不要忘记在您的 html 中包含 KaTeX 样式表：

<link
  rel="stylesheet"
  href="https://cdn.jsdelivr.net/npm/katex/dist/katex.min.css"
/>

不过，稍微复杂一些的公式：

1
2
3

$$
\sum\limits_{{\rm{i}} = h - 1}^1 {{2^{i - 1}}2(h - i) = } \sum\limits_{{\rm{i}} = h - 1}^1 {{2^i}(h - i) = } \sum\limits_{j = 1}^{h - 1} {{2^{h - j}}j \le 2n\sum\limits_{j = 1}^{h - 1} {\frac{j}{{{2^j}}}} }  \le 4n
$$

就会与markdown的解析出现问题，Hexo会出现 Nunjucks错误，这通常是因为公式中含有{{ }} ，把公式中不必要的{}删除或在两个{{}} 之间添加空格加以区分即可。

处理后即可正常显示：

1
2
3

$$
\sum\limits_{ {\rm{i} } = h - 1}^1 { {2^{i - 1} }2(h - i) = } \sum\limits_{ {\rm{i} } = h - 1}^1 { {2^i}(h - i) = } \sum\limits_{j = 1}^{h - 1} { {2^{h - j} }j \le 2n\sum\limits_{j = 1}^{h - 1} {\frac{j}{ { {2^j} } } } }  \le 4n
$$

$\sum\limits_{ {\rm{i} } = h - 1}^1 { {2^{i - 1} }2(h - i) = } \sum\limits_{ {\rm{i} } = h - 1}^1 { {2^i}(h - i) = } \sum\limits_{j = 1}^{h - 1} { {2^{h - j} }j \le 2n\sum\limits_{j = 1}^{h - 1} {\frac{j}{ { {2^j} } } } } \le 4n$

任务列表

1 2	# https://www.npmjs.com/package/markdown-it-task-list-plus npm install markdown-it-task-list-plus --save

_config.yml

# 在hexo-renderer-markdown-it配置中（同上方图片路径问题的配置位置）
plugins:
  - 'markdown-it-task-list-plus'
  # Other plugins...

在主题中添加以下样式即可解决任务列表样式问题。

your_theme/source/css/_custom.styl

/*
* [x] 已完成
* [ ] 未完成
*/
li.task-list-item {
  list-style-type: none;
}

li.task-list-item .task-list-item-checkbox-span {
  margin: 0 0.2em 0.25em -1.6em;
}

已完成
未完成

Hexo常用标签

图片标签

图片标签是一个精心设计的应对各种尺寸插图的标签，对于大图，可以放置一个「下载」按钮，语法格式如下：

来自 Github 的图片

{% image src [description] [download:bool/string] [width:px] [padding:px] [bg:hex] %}  
参数说明
src: 图片地址  
description: 图片描述  
download: href # 下载地址，设置此值后鼠标放在图片上会显示下载地址，如果下载地址为图片地址，可以设置为 true  
width: 200px # 图片宽度  
padding: 16px # 图片四周填充宽度  
bg: '#ffffff' # 图片区域背景颜色，16进制，没有底色的图片，可以填充 `bg:var(--card)` 动态颜色，能够适配暗黑模式

注：使用该标签时不用使用相对路径，直接使用Hexo资源文件夹的绝对路径即可，如Hexo资源文件夹source中有images文件夹，则引用其中的图片仅需要用/images/photo.png路径即可访问，这和markdown的方式有区别。

ablock 普通块容器

Stellar v1.12.0

因为原 noteblock 标签在升级到 hexo 6.0 之后跟官方库冲突了，官方一直没有解释原因，后不得不改名：
noteblock -> grid -> border
详情见：#172

1
2
3

{% ablock [title] [color:color] [child:codeblock/tabs] %}  
...  
{% endablock %}

{% ablock Stellar v1.12.0 color:warning %}  
因为原 noteblock 标签在升级到 hexo 6.0 之后跟官方库冲突了，官方一直没有解释原因，后不得不改名：  
noteblock -> grid -> border  
详情见：[#172](https://github.com/volantis-x/hexo-theme-volantis/issues/712)  
{% endablock %}

folding 折叠容器

点击展开

这是一个容器

折叠块标签的语法格式为：

1
2
3

{% folding title [open:bool] [color:color] %}  
content  
{% endfolding %}

1
2
3

# 参数说明
open: true/false  
color: red/orange/yellow/green/cyan/blue/purple/light/dark

默认打开的代码折叠框

1
2
3

func test() {  
  print("hello world")  
}

1
2
3

{% folding child:codeblock open:true color:yellow 默认打开的代码折叠框 %}  
代码块  
{% endfolding %}

folders 多个折叠容器聚合

样式相比 folding 简单一些，适用于多个折叠标签平铺显示的场景，例如题目列表：

题目1

这是答案1

题目2

这是答案2

题目3

这是答案3

代码如下：

{% folders %}  
<!-- folder 题目1 -->  
这是答案1  
<!-- folder 题目2 -->  
这是答案2  
<!-- folder 题目3 -->  
这是答案3  
{% endfolders %}

tabs 分栏容器

支持设置 align:center 来使内容居中
设置默认激活的标签方式为 active:1 （使用默认格式降低学习成本，且显式声明可读性更强）
不需要  来作为结束标识（因为 Stellar 会自动判断）
不需要 tabs id 来保证唯一性（因为 Stellar 会设置唯一标识）
不支持 @icon 方式设置图标（因为 Stellar 不再内置 fontawesome 图标库）
轮廓样式简化，可以搭配其它容器类标签嵌套使用。

1 2	let x = 123 print("hello world")

a	b	c
a1	b1	c1
a2	b2	c2

{% tabs active:2 align:center %}

<!-- tab 图片 -->
{% image /assets/wiki/stellar/photos/hello@1x.png width:300px %}

<!-- tab 代码块 -->
\```swift
let x = 123
print("hello world")
\```

<!-- tab 表格 -->
| a | b | c |
| --- | --- | --- |
| a1 | b1 | c1 |
| a2 | b2 | c2 |

{% endtabs %}

grid 网格分区容器

左侧内容

右侧内容

bg 为可选参数，默认没有背景，可设置为 block/card 两种样式

{% grid bg:card %}  
<!-- cell left -->  
<center>左侧内容</center>  
<!-- cell right -->  
<center>右侧内容</center>  
{% endgrid %}

链接卡片

不带摘要的样式：

https://csthenry.github.io/2023/02/25/qt_mysql/https://csthenry.github.io/2023/02/25/qt_mysql/

带摘要的样式：

https://csthenry.github.io/2023/02/25/qt_mysql/

不带摘要的样式：  
{% link https://csthenry.github.io/2023/02/25/qt_mysql/ %}  
带摘要的样式：  
{% link https://csthenry.github.io/2023/02/25/qt_mysql/ desc:true %}

导航栏

文章内也可以插入一个导航栏：

1	{% navbar active:1 [文章](/) [项目](/wiki/) [留言](#comments) [GitHub](https://github.com/csthenry/) %}

引用

这是Hexo文档

热门话题

1 2	适合居中且醒目的引用：{% quot 这是Hexo文档 %} 支持自定义引号：{% quot 热门话题 icon:hashtag %}

复制行

对于单行内容，可以使用 copy 标签来实现复制功能：

您可以设置 git:https 或者 git:ssh 或者 git:gh 来快速放置一个 git 仓库链接：

{% copy curl -s https://sh.xaox.cc/install | sh %}  
{% copy width:max curl -s https://sh.xaox.cc/install | sh %}  
{% copy git:https xaoxuu.com/hexo-theme-stellar %}  
{% copy git:ssh xaoxuu.com/hexo-theme-stellar %}  
{% copy git:gh xaoxuu.com/hexo-theme-stellar %}

checkbox 复选

普通的没有勾选的复选框

普通的已勾选的复选框

显示为加号的绿色的已勾选的复选框

显示为减号的黄色的已勾选的复选框

显示为乘号的红色的已勾选的复选框

{% checkbox 普通的没有勾选的复选框 %}  
{% checkbox checked:true 普通的已勾选的复选框 %}  
{% checkbox symbol:plus color:green checked:true 显示为加号的绿色的已勾选的复选框 %}  
{% checkbox symbol:minus color:yellow checked:true 显示为减号的黄色的已勾选的复选框 %}  
{% checkbox symbol:times color:red checked:true 显示为乘号的红色的已勾选的复选框 %}

# 参数
checked: true/false  
color: red/orange/yellow/green/cyan/blue/purple  
symbol: plus/minus/times