建站记录 1.0｜Hexo+Butterfly

Start

总体方案：采用 Hexo+Butterfly 的静态博客方案；VS Code + Typora 编辑预览，git 版本管理 + GitHub Action 部署。

doc https://hexo.io/zh-cn/docs/
群晖下运行：需要套件 Git Server 和 Node.js

安装

npm install -g hexo-cli  //安装Hexo

hexo -v  //查看Hexo的安装是否正常
hexo init hexo  //初始化Hexo
cd hexo
npm install  //安装依赖包

命令行

hexo s // 启动本地服务器
hexo s -p 8082 // 设置端口，默认的端口是 4000
hexo clean // 清除本地缓存
hexo generate // 初始化文件
hexo deploy // 提交文件到服务器

# 本地调试
hexo clean && hexo server --draft --debug
# 部署
hexo clean && hexo generate 
hexo douban  # 用了douban插件
hexo deploy

需求/TODO

主题

NexT 7.3k
- 是基于原来的 NexT 项目 (15.7k)的社区维护版本；
- 中文教程 http://theme-next.iissnan.com/；
- 推荐的插件列表 ⭐️
Concise
Butterfly 2.9k
- Card UI Design; Two Column design;
- 主页教程；
- 美化/魔改方案合集
Volantis
- 文档写得超赞 ⭐️
Fluid
- Material Design
- 主页和文档也不错子

插件汇总

压缩混淆生成的 HTML、CSS、JS 文件 hexo-all-minifier 插件
跨平台环境变量 cross-env 跨平台环境变量设置脚本

GiTalk

实用

hexo-abbrlink 生成短链接
hexo-wordcount 字符统计
hexo-generator-search 本地搜索
hexo-generator-feed 生成 RSS
hexo-generator-sitemap 生成 sitemap
hexo-generator-index 文章置顶

需求

hexo-butterfly-douban 索引豆瓣列表

Math

hexo-renderer-pandoc 基于pandoc 的渲染？
- Latex支持比较好，参见 Next 的说明文档。替换默认的 hexo-renderer-marked
- 并不推荐 hexo-renderer-kramed ，实测也出了点问题

测试中

hexo-offline PWA？

主题相关

hexo-butterfly-douban 豆瓣索引
hexo-butterfly-artitalk 基于 ArtiTalk 的说说页面，Butterfly 主题自带了

功能项配置｜ Butterfly

也算尝试了好几个博客方案了；其中方案的入门难度、配置难度、定制化程度各有差别，但找到一个好用的，然后深入了解才是正道。

这次详细看了 Buttery 的配置说明，也正好明确了个人博客的各种需求：从网页排版（页面设置、代码、图片、Math）、交互形式（评论、聊天室、分享）到增值（sitemap、广告、赞助、版权信息、复制行为）、网页性能相关（图片管理压缩、PWA等）。

以下框架主要摘录自 Butterfly 的配置说明。

开始

快速开始
- 安装
- 应用主题
- 安装插件 hexo-renderer-pug hexo-renderer-stylus
- 升级建议

页面

主题页面
- Front-matter
- 标签页 hexo new page tags
- 分类页
- 友情链接 hexo new page link
  - 链接在 source/_data 中的 link.yml 编辑
- 图库
  - 子页面
- 404页面

Front-matter

以下分别是 post 和 page 的 Front-matter 配置选项

title: {{ title }}
date: {{ date }}
updated: {{ date }}
tags: 
  - 
categories: 
  - Software
keywords: 
  - 
description: 
top_img: 
cover:      # 文档页的小图，可以和 top_img 不同
sticky: 2   # 文章置顶，数字越大优先级越高
mathjax: 

# 以下是可调选项，自己一般用不上
comments:
toc:
toc_number:
copyright:
copyright_author:
copyright_author_href:
copyright_url:
copyright_info:
katex:
aplayer:
highlight_shrink:
aside:

title: {{ title }}
date: {{ date }}
updated: {{ data }}
aside: true
description:
top_img: 

# 可选项
type:
comments:
keywords:
mathjax:        # 显示mathjax(当设置mathjax的per_page: false时，才需要配置，默认 false)
katex:          # 显示katex(当设置katex的per_page: false时，才需要配置，默认 false)
aplayer:        # 在需要的页面加载aplayer的js和css,请参考文章下面的 音乐 配置
highlight_shrink: # 配置代码框是否展开(true/false)(默认为设置中highlight_shrink的配置)

主题配置

参见主题配置1；主题配置2；

语言
网站资料
导航菜单
- 标签、分类、友情链接
代码
- 高亮主题
- 复制、代码框展开/关闭、换行、高度限制
社交图标
- 支持 font-awesome v5
主页文章节选
- 基于 description 字段或者自动生成
顶部图
- 分别设置主页、默认；归档页；标签、类别的默认和各自的顶部图。其他page的可以在 top_img 中设置
- 配置的值支持：留空、链接、颜色、透明 transparent、不显示 false
文章置顶
- 在文章中设置 sticky: 1 。数值越大，置顶的优先级越大。
文章封面
- cover 属性定义。可分别设置 index, aside, archives 中是否显示、显示的位置；默认图；放多张图片可以随机选择。自由度很高
文章页相关配置
- 文章meta显示：创建、更新日期；相对日期；分类；标签；描述文字description
- 文章版权
- 文章打赏
- TOC：可用 toc_number 和 toc 在文章中单独控制
- 相关文章：根据文章tags的比重来推荐
- 文章锚点 anchor：随着页面滚动根据标题ID替换文章链接
- 文章过期提醒
- 文章编辑按钮
- 文章分页按钮
头像 avatar
图片描述
复制相关配置｜字数超过一定有最后加上版权信息
Footer设置｜博客年份、自定义文本
右下角按钮
- 简繁、夜间模式、阅读模式、字体大小
侧边栏设置
- 侧边排版 aside
- 访问人数｜busuanzi
- 运行时间
- 最新评论
- 自定义添加栏目
Tag Plugins
- Note (Bootstrap Callout) 介绍了两种语法；第二种可自定义 icon
- Gallery相册图库。这里写了一个 <div class="gallery-group-main"> 来放 galleryGroup ，似乎只是为了方便计算分割线位置
- tag-hide 隐藏一部分
- mermaid
- Tabs
- Button
- inlineImg
- label 高亮词句 {% label text color %} ，可选 default/blue/pink/red/purple/orange/green
聊天区
Math
- 还是MathJax方便些
美化/特效
- 自定义主题色
- 网站背景
- footer 背景
- 打字效果用了 activate-power-mode
- 背景特效
- 鼠标点击效果
- 页面美化｜改变ol、ul、h1-h5的样式
- 自定义字体和字体大小
- 网站副标题（打字机效果）
- 主页top_img显示大小
- 页面加载动画preloader（加载速度）
PWA
- 需要插件 hexo-offline
- 可以尝试用 Google 的 Lighthouse 来检查网页性能
字数统计，需要 hexo-wordcount 插件
图片大图查看模式｜但张图全屏；图片组合
Snackbar 弹窗
其他配置
- CSS 前缀。有些 CSS 并不是所有浏览器都支持，需要增加对应的前缀才会生效。（增加20%体积）
- Open Graph。在 head 里增加一些 meta 资料，例如缩略图、标题、时间等等。当你分享网页到一些平台时，平台会读取 Open Graph 的内容，展示缩略图，标题等等信息。
- Instantpage。当鼠标悬停到链接上超过 65 毫秒时，Instantpage 会对该链接进行预加载，可以提升访问速度。
- Pangu。在网页中所有的中文字和半形的英文、数字、符号之间插入空白。
Pjax｜点击链接，通过ajax更新页面需要变化的部分，然后使用HTML5的pushState修改浏览器的URL地址；不用重复加载相同的资源（css/js），从而提升网页的加载速度。
- 对于一些第三方插件，有些并不支持 pjax 。可以把网页加入到 exclude 里
Inject ｜添加额外的 js/css/meta 等等东西
CDN
- 这里用的是 jsdelivr

disqus
giscus 一个新的基于 GitHub Discussions 驱动的评论系统；主页；

进阶

进阶教程
- 音乐
- 电影，用 hexo-butterfly-douban
- 自定义代码配色
- 自定义侧边栏
- jQuery 加载
  - 主题已于 3.4.0 去除 jQuery 的引用，但是部分功能仍需要加载 jQuery（Justified Gallery和 fancybox)。
  - 如果你仍需要使用 jQuery，可以调用主题提供的 function，防止 jQuery 多次加载。
- Gulp压缩
  - Gulp 是一款自动化构建的工具，拥有众多的插件。而我们只需要使用到几个插件来压缩Html/css/js。
- PWA
  - 渐进式网络应用程式（英语：Progressive Web Apps，简称：PWA）是一种普通网页或网站架构起来的网络应用程式，但它可以以传统应用程式或原生移动应用程式形式展示给用户。
  - 此方法是使用 Service Worker。我们使用 Workbox 这个工具生成 sw.js 以快速实现 Service Worker ，并实现页面的预缓存和页面更新后的提醒功能。

Math

Butterfly 的说明文档用的 hexo-renderer-kramed 有些小问题，还是参见 Next，使用 hexo-renderer-pandoc 渲染。

注意卸载默认的 hexo-renderer-marked ；而 hexo-renderer-kramed 不会冲突但装了也没啥用。
但主题的配置文件还是要打开的，Next 主题的参见上链接；Butterfly 则是在主题配置中设置 mathjax 下的 enable: true。

Latex 补课

Latex math mode

以下是（单行）公式的语法，内部排版就是用 math mode。f rom here.

Method	Special Characteristics	Usage
$....$	None	In-line math
`\begin{equation} \end{equation}`	Goes to a newline and center equation with label	Equations
`\[ ....\]` or `$$...$$`	Goes to a newline and center equation	Equations with no label

Latex 多行公式

在 Typora 和 Code 中，$$ 包裹的直接可用 \\ 分行，但不符合 Latex 语法；

以下 from 知乎

单行公式
- 可以用 \[ \] 包裹，不编号；或者 equation 环境，编号。
多行公式
- 简单的多个公式的堆积，我们可以用 gather 和 align 环境。gather 环境中，所有的公式都是居中的；而 align 环境可以用 & 符号指定位置对齐（比如按等号对齐）。
  - 两个环境都默认编号可以用 \notag \nonumber 指定不编号！【在 Typora 中不编号】
- 如果我们是要把一个公式拆分成多行来书写，并给出一个单独的编号，那么上面的两个环境就不那么适用了。在这里为大家介绍 split 环境。split 环境需要嵌套在 equation 环境中使用，也支持像 align 环境中那样的对齐方式（但不能多列对齐）【而在 Typora 下不在 equation 下也可以，但本身就支持 \\ 换行也不需要】
- 想把多个公式组合成一个大的公式，需要用到 cases 环境（也需要在 equation 环境中）；注意在每个 case 中，公式都会被变成行内公式。可以用 \dfrac 命令来强制让分式变成行间公式。（如果我们想简单地解决这个问题，就需要使用 mathtools 宏包定义的 dcases 环境，用法和 cases 完全相同，但是可以以行间公式的形式来排版每个 case。）

区分 `align*` 和 `aligned`

aligned 必须在 $$ 或 equation 即单公式中使用，可以认为是对于单公式的拓展；
而 align* 则是 align 的不加编号的版本，多公式。
两者区别可体现在行距上。

Code/Typora 实践

在 Code 中预览/编辑
- 使用插件 Markdown Preview Enhanced 可以预览 gather 等多公式环境；
- 而默认的不可预览多公式环境，但支持 aligned（可以理解为仅支持 Latex 中的 $$ 环境而未引入 amsmath 包）；
- 需要注意的是，尽管在这两个环境中均支持直接 \\ 换行，但是 hexo-renderer-pandoc 渲染结果是不会换行的，因此还是需要用 1. split, cases, aligned, gather 等环境实现单公式的换行（不需要在 equation 包裹，可理解为 Markdown 中的 $$ 内部默认为 Latex 的 $$ 语法）；2. 使用 align, gather 等多公式环境
最佳实践
- 在 Typora 或 Code 中使用 Markdown Preview Enhanced 预览编辑；需要注意的是单公式的换行；
- 关于公式编号， Markdown Preview Enhanced 和 pandoc 渲染结果是一致的，而 Typora 中则无；
- 还有之前一些语法问题
  - Markdown Preview Enhanced 默认用的是 KaTex 引擎，不支持 E_\hat{F} 等结果；之前用 hexo-renderer-kramed 会报错，而 pandoc 不会。不支持的包括
    - E_\hat{F} 等上下标复杂的情况，必须用 E_{\hat{F}}；
  - 很奇怪 pandoc 默认不支持 \sqrt{{1\over B-1}} 这样的语法，还是用 \frac{}{} 比较好
- 不太清楚不同渲染引擎对于（不规范）语法的处理，总而言之，使用更为规范的 Latex 可以避免很多问题！

公式引用

Next 主题中添加了公式引用的功能，需要放在 equation （直接放在 $$ 中无效！）或 align 等环境中
- 给公式一个 \label{} 标记（tag）
- 采用 \eqref{} 进行引用（相较于 ref 引用两边有括号）。
- 实测在 Butterfly 主题中也能用！
在 Typora 中不支持；Code 的 Markdown Preview Enhanced 中 Math Rendering Option 中也只有 Katex 可选，无法渲染引用；

Start

需求/TODO

主题

插件汇总

功能项配置｜ Butterfly

开始

页面

Front-matter

主题配置

评论

进阶

Math

Latex 补课

Latex math mode

Latex 多行公式

区分 align* 和 aligned

Code/Typora 实践

公式引用

区分 `align*` 和 `aligned`