Hexo笔记(一)——安装, Markdown写作与主题
介绍使用Hexo配置本博客和用Markdown进行博文写作的基本方法和技巧,为撰写排版更好更清晰的技术文本作准备。
前言
之前代码从来都是习惯在组里LinuxPC或者学校HPC上写的,但时常会因为不在随手可及的地方觉得不安。年前从学长手中购入MBP作为自己今后的代码生产主力,同时跑一点简单的科学代码,也想着把Linux和原笔记本上的一些代码项目移到Mac上。这自然就包括了这个Hexo博客。
尽管技术写作和笔记并没有停滞,但是一直处于比较粗浅的笔记状态,就没有敢上传到这里(还是希望比较成型后再传)。更主要的一个原因是觉得这个博客的界面配置还始终是未完成状态,自己不甚满意,平时也没有时间好好研究JavaScript和Nodejs代码,最后就没有上传笔记的动力了,导致这个个人域名完全处于浪费钱的状态。于是想趁着春节假期把博客框架好好整一整。
这篇文章内所有命令均在macOS High Sierra (10.13)或Mojave (10.14)下执行。默认Homebrew基本配置完成,包括本文所涉及的Git和Nodejs开发环境等,执行命令前需要拥有GitHub账户并完成Git全局配置。
基本配置
GitHub Pages
个人博客服务端使用Git Pages,它是GitHub专为个人、组织用户和代码项目提供的页面服务,通过Git将本地HTML和CSS文件结构部署(deploy)到Page仓库master分支来实现。创建个人页面的方法是
- 类似于一般代码仓库,在GitHub主页上创建名为
[email protected]
的仓库。以自己为例的话就是[email protected]
的仓库。个人主页必须以此种方式命名。 - 进入新建的仓库,点击Setting标签,在
Options
下翻到GitHub Pages
标签,可以看到这一部分处于激活模式。可与你的其他一般仓库(没有制作doc
分支用于文档网站)进行对比。一般代码仓库也可以通过Setting->Options->GitHub Pages
配置项目文档页面,需要选择doc
分支承载HTML文件结构。 - 回到Code标签,新建
hexo
分支,并将其设为默认分支。之后master
分支用来存储静态网页,hexo
分支存储博文和主题的源文件。
安装Hexo和Git部署模块
Hexo是一个模块集成的HTML和CSS文件结构生成程序,用户可以把精力集中在博文内容上,而让Hexo管理界面风格和样式。通过node包管理器npm
安装hexo
npm hexo install |
安装完成后,在某路径下,创建本地Hexo文件夹并初始化。以my-hexo-dir
为例
mkdir my-hexo-dir |
初始化后,文件夹内结构为
. |
node_modules
内包含在搭建网站时可能需要的模块,比如数学渲染模块hexo-renderer-mathjax
和Git部署模块hexo-deployer-git
,后者是我们通过Git部署GitHub Pages所必须的。安装模块通过npm
完成,如
npm install hexo-deployer-git --save |
加入save
选项会更新package.json
内的包依赖。 --save
和--save-dev
选项的比较可见这篇文章。
修改_config.yml
中网络链接和与部署方法相关的代码块以启用git
部署
# URL |
这样一来,通过Hexo发布自己个人GitHub Pages博客的必要准备已经完成了。在my-hexo-dir
下键入以下命令生成静态博客
hexo g # 使用Hexo生成HTML |
在浏览器访问https://localhost:4000
即可看到生成的Hexo博客。通过
hexo d |
可以将静态页面推送到GitHub Pages中, 此时就能在username.github.io上看到博客了.
主题选择
本博客使用的是从PytLab处Fork来的Freemind主题。首先将仓库下载到本地themes
文件夹内
cd themes |
下载完成后,修改根目录下_config.yml
文件中的theme
标签以启用Freemind
theme: freemind |
若对其他主题感兴趣,可自行google并通过类似的方法架设。此时重新生成并访问,可以发现博客已经从Landscape变为Freemind主题。
开始写作: 从模板新建
在基本设置完成以后,我们就可以开始写作博客了。通过Hexo内建指令new
创建新的博文
hexo new post pname |
这会在source/_posts
下创建Markdown文件pname.md
和文件夹pname
,后者用于存放md内引用的图片或代码文件。新建文件名的默认格式可通过修改_config.yml
中的new_post_name
来调整,例如
new_post_name: :year-:month-:day-:title.md # yyyy-mm-dd-pname |
此时按上面指令新建pname
将得到2018-02-21-pname.md
和文件夹2018-02-21-pname
。如果文章本身未成型,想先写一个草稿,用
hexo new draft dname |
会在source/_draft
下创建dname.md
文件和dname
文件夹。草稿写作完成后可用命令
hexo publish dname |
发布,此时Hexo会将dname.md
和dname
按照new_post_name
的格式重命名后,移动到source/_post
文件夹下,不需要自己手动改名。
Hexo写作
Hexo博客正文写作基于Markdown语法,网络上已经有非常多的教程和帮助文档,例如我现在在Dash中使用的cheat sheet。对于Hexo比较特别的是,为了识别博文的基本信息,我们需要一个front matter。另外,除了基本Markdown语法以外,我们还可以使用开源作者编写的Hexo渲染器及主题允许的各种特性,来丰富我们的写作手段。
Front matter
对任一篇Hexo博文,文件夹非必须,但一定会有对应的Hexo要求博文的.md
文件。.md
文件开头需要有一个YAML格式的front matter。根据该front matter,Hexo可识别博文的标题、创建日期、标签、分类等各种特征以及需要用到的渲染器。Front matter的基本格式为
|
利用hexo new post
产生的博文,front matter会套用scaffold
中的post.md
,相当于post的初始化模板
|
可根据自己需要修改模板,如增加目录toc
、归类categories
以及首页图片feature
。当存在与md文件名一致的文件夹时,md中图片和代码引用会在该文件夹中搜索,只需要把欲引用的图片代码放入文件夹,将引用路径设为文件名即可。
基于MathJax的数学公式插入
由于专业原因,可以预想到很多时候需要插入大量的公式,实现方法是使用浏览器公式引擎MathJax。推荐使用hexo-renderer-mathjax,安装很方便,对_config.yml
的改动量也很小。通过npm安装
npm install hexo-renderer-mathjax --save |
安装完就可以正常使用。如果出现无法渲染的情况,在_config.yml
中加入:
Plugins: |
输入行内公式可使用$math$
,例如
$P=iGG, G=\frac{1}{\omega - \hat{H}_{\text{KS}}}$ |
效果:$P=iGG, G=\frac{1}{\omega - \hat{H}_{\text{KS}}}$
输入公式块可使用$$mathblock$$
,例如
$$ \nabla^2 \phi = -\rho $$ |
效果:
$$\nabla^2 \phi = -\rho$$
此外还可以使用\begin{equation}\end{equation}
来产生带编号的公式,但需要对hexo-renderer-mathjax包的内容进行修改。将node_modules/hexo-renderer-mathjax/mathjax.html
中间MathJax.Hub.Config
函数改为
MathJax.Hub.Config({ |
即增加TeX
一行(不要忘了前面的逗号,
)。
$$\begin{equation} |
效果:
$$\begin{equation}
\begin{aligned}
a=b+&c \\
&+e+f
\end{aligned}
\end{equation}\label{eq1}$$
还可以用$\eqref{eq1}$
来引用公式$\eqref{eq1}$。上面equation例子还需要注意的是,默认的Markdown渲染器会将两个斜线\\
渲染为\
,从而导致无法转行。这里根据网络上的办法,修改node_modules/marked/lib/marked.js
,将
escape: /^\\([\\`*{}\[\]()#+\-.!_>])/, |
改为
escape: /^\\([`*\[\]()# +\-.!_>])/, |
移除marked对花括号和反斜线的渲染。如果出现下划线渲染问题,再将em:
一行从
em: /^_([^\s_](?:[^_]|__)+?[^\s_])_\b|^\*((?:\*\*|[^*])+?)\*(?!\*)/ |
改为
em: /^\*((?:\*\*|[\s\S])+?)\*(?!\*)/, |
以移除对下划线_
的渲染. 看一下结果
Markdown | 类型 | 渲染结果 |
---|---|---|
$a_b$ |
公式 | $a_b$ |
$a^*$ |
公式 | $a^*$ |
$a^* b^*$ |
公式 | $a^b^$ |
$a^\ast b^\ast$ |
公式 | $a^\ast b^\ast$ |
*em* |
强调文本 | em |
_em_ |
强调文本 | _em_ |
可以看到, 当公式里同时出现两个星号时, 公式将无法正常渲染. 一种解决方案是用\ast
代替*
.
由于Mathjax的CDN在17年中退役, 修改mathjax.html
中CDN脚本一行
<script type="text/javascript" async src="https://cdnjs.cloudflare.com/ajax/libs/mathjax/2.7.1/MathJax.js?config=TeX-AMS-MML_HTMLorMML"></script> |
链接自己博客内的文章
{% post_link md-filename-wo-extension %} |
如
{% post_link compile_VASP_on_macOS %} |
{% post_link f2py-1 %} |
图片说明
npm install --save hexo-image-caption |
在_config.yml
中加入
image_caption: |
并按照这一条PR修改node_modules/hexo-image-caption/index.js
.
流程图
npm install --save hexo-filter-flowchart |
直接使用即可. 具体语法参考flowchart.js官网
对于比较长的流程, 需要在_config.yml
中
Freemind特性
首页摘要
在要作为摘要的文字后面加上<!--more-->
,首页将只显示<!--more-->
前面的内容,同时出现”Read More”的按钮。摘要内容仍然会在正文中显示。
标签插件
使用标签插件(Tag plugins)可以使得文章的可读性更好。在这里我参考了wxpan提供的样例。总结一些tag plugins用法,包括一般Hexo和Bootstrap的tag plugins。在使用插件前,需要先安装Bootstrap
npm install hexo-tag-bootstrap --save |
标签(label)
{% label default %} |
效果是插入一个醒目的颜色小标签
default warn succ danger prim info
警报(alert)
{% alert warning %} 这是一个警告类型的警报 {% endalert %} |
效果是插入一个带特定背景色的文字块,左上方含有标识文本性质的符号。
这是一个警告类型的警报
这是一个危险类型的警报
这是一个成功类型的警报
这是一个信息类型的警报
徽章(badge)
{% badge 徽章测试 %} |
效果是徽章测试
Freemind调教
若非特别指出,所有的关于Freemind的调教都是在themes/freemind
文件夹内,不要与Hexo根目录混淆。
网站图标
Hexo会在根目录下source/assets/images/favicon/
内寻找图片作为网站图标。另一种方法是在_config.yml
内通过编辑favicon
标签显示指定
网站图标设定功能在layout/_partial/head.ejs
中定义
<% if (theme.favicon){ %> |
在_config.yml
中设置
favicon: True |
然后将命名为icon.png
的网站图标图片放入Hexo根目录下的source/assets/images/favicon
下即可。也可以修改href
属性,换成自己想要的路径。
Wiki型浮窗式的脚注
用npm
安装hexo-reference
npm install hexo-refernce --save |
在Hexo根目录_config.yml
中启用插件
Plugins: |
为了跟网页主体风格相一致, 稍微修改了一下其中的源码(hint.min.css
)以调整浮窗文字的背景颜色, 置于主题CSS文件夹下
sed 's/b34e4d/1863a1/g' node_modules/hexo-reference/src/hint.min.css > themes/freemind/source/css/hint.min.css |
同时修改index.js
, 将href
的CDN地址改为本地地址
cd node_modules/hexo-reference/ |
测试一下效果.[1]
在首页摘要中移除alert效果
在<!--more-->
前使用Bootstrap的alert对象时, 首页摘要显示也会出现的alert的效果. 这可以通过修改hexo库中的excerpt.js来移除alert的div标签来实现.
// 位置在node_modules/hexo/lib/plugins/filter/after_post_render/excerpt.js |
边栏链接及链接图标
在_config.yml
内编辑links
标签,每一条短线对应一个链接条目
links: |
其中icon
对应链接旁显示的图标。本示例使用了Font Awesome提供的图标,该项目提供的全部图标可以在这里找到。
谷歌统计GA
使用谷歌账号登录谷歌统计, 在管理标签中找到用户管理。在媒体资源设置中找到自己的跟踪ID,并设置默认跟踪网址, 然后在跟踪信息-跟踪代码中,将全局网站代码粘贴到layout/_partial/after_foot.ejs
底部, 并把明文的GA ID改成<%= theme.google_analytics.siteid %>
.
在GA主页上, 可以通过”管理-过滤器-添加过滤条件”来排除来自特定IP的流量. GA通过浏览器工作, 而浏览器不会读取MAC地址, 因此无法通过检测MAC地址的方式排除特定设备的流量.
不蒜子站点和页面统计
将不蒜子整合到Freemind中, 以支持站点访客数统计和页面访问量统计. (GA也可以完成, 但没精力读API了…) 在_config.yml
中加入
busuanzi: |
以提供一致的开关. 在layout/_partial/post/analytics.ejs
中引入js
<% if (theme.busuanzi.pageview || theme.busuanzi.visitor){ %> |
然后在layout/_partial/footer.ejs
中加入总访客数标记
<% if (theme.busuanzi.visitor) { %> |
在layout/_partial/post/meta.ejs
中加入页面总访问数
<!-- page view by busuanzi --> |
页面每被点击一次, 总访问数就加一.
全站字数统计
使用hexo-wordcount. 类似不蒜子, 在layout/_partial/footer.ejs
加入
<% if (theme.wordcount.site) { %> |
在YAML中开启
wordcount: |
修改页尾标记
在layout/_partial/footer.ejs
中修改.
配色修改
由于个人偏好蓝色和深绿色,需要简单修改一下博文大小标题和行间代码的配色。在source/css/highlight.css
中修改行间代码的CSS样式
code { |
在source/css/style.css
中修改文章中大小标题的样式
h2{ |
文字两端对齐
在source/css/style.css
中加入
p { |
DISQUS评论
注册DISQUS账号,选择”I want to install disqus on my site”,使用universal code安装,将这部分代码拷贝到layout/_partial/post/comment.ejs
中。接下来配置Disqus,主要是Website Name
和Website URL
,前者我设置为我的shigaro。然后在Hexo根目录_config.yml
下加入
# comment |
三线表
在source/css/style.css
中加入
/* 居中三线表 */ |
背景图片
在layout/layout.ejs
中, 修改body标签, 增加一段ejs
<body <%- partial('_partial/background') %>> |
新建layout/_partial/background.ejs
<% if(theme.background) { %> |
body-img-background
类的样式由source/css/style.css
控制
/* fixed image background by minyez*/ |
然后在_config.yml
中加入
background: background.png |
再把想作为背景的图片background.png放到Hexo根目录source/assets/images/
下面就可以了. 目前样式参考了这条链接.
TODO
- Bugfix: 点击
Software
的category徽章后显示的文章不全. 启用根目录下category_generator
并将per_page
设为0即可解决. - 代码块复制功能.
- Quotes页面, 存储一些摘句, 同时有一个即时搜索引擎.
- 文章中侧边栏随正文一同滚动. 对于TOC较长的情形, 鼠标移动到侧边栏上对TOC滚动浏览.
总结
笔者基于Hexo框架和Freemind主题搭建了个人博客,根据自己的需求进行了自定义,并利用MathJax渲染器和Bootstrap特性进行了Markdown写作。
参考
LaTeX Equation Numbering Done Right in Hexo
另一个渲染器hexo-math及一个讨论其用法的Issue
如何在自己的主题下实现MathJax支持:在Hexo中渲染MathJax数学公式
代码块复制:HEXO优化之(二)—-添加复制功能
更新
2019-05-07
增加基于hexo-reference
的wiki浮窗式的脚注. MathJax: 比较各种情况下*
和_
的渲染结果. 更改CDN.
2019-05-10
增加对不蒜子统计的支持. 去掉了Archives不必要的下拉菜单, 直接进入archives
页面.
2019-05-22
增加背景图片, 位置由YAML中background
变量指定.
2019-05-25
利用hexo-wordcount
进行全站和页面字数统计.
2020-06-30
首页摘要中移除alert效果.
- 1.这是一个脚注测试 ↩