使用 Hexo 与 NexT 搭建博客的避坑总结z

原文地址http://yangfch3.com/2016/05/08/hexo-experiences/

这个博客是使用 Hexo 与 NexT 搭建起来的,在搭建的过程中遇到了一些莫名其妙的问题,记录在此。对于官方文档已经有介绍的,在此不表。

1 Hexo

  1. Hexo 是有中文文档的,当然更推荐看英文文档
  2. 关于几个文件夹功能的释义
    • scaffolds为模板文件夹,模板用于预先定义 new 出来的文章的 layout;
    • source_drafts文件夹用于放置草稿,使用hexo --draft可查看所有草稿文章;草稿完稿后可以使用publish命令发布到_post文件夹内,等待generate
  3. 自定义的其他模板和 post 模板相同,new 出来的文章都将储存到source/_posts文件夹
  4. 当你不想你的文章被发布,同时又不想删除文章,将文章的Front-Matter中的layout:设为false
  5. 文章的Front-matter采用 YAML 语法格式,多个标签与分类不是用逗号隔开,而是采用 YAML 中的列表/并列写法
  6. Hexo 支持更强大的quote块:可以添加引用作者、来源、链接等;在有这些需求的时候可以引用
1
2
3
{% blockquote [author[, source]] [link] [source_link_title] %}
content
{% endblockquote %}
  1. Hexo 支持更强大的 code 块:支持为 code 块添加标题和链接;当我们需要引用某个链接内的代码时可以使用,一般情况下使用 md 的代码块语法即可
1
2
3
{% codeblock [title] [lang:language] [url] [link text] %}
code snippet
{% endcodeblock %}
  1. 引入 gist 时,插入fileName似乎会失败,所以,引入 gist 时只需要使用gist hash-id即可
1
{% gist 5b3ee7efd535ab63cd56 %}
  1. Hexo 支持更使用特定的语法,插入指定大小的图片,如下:
1
2
3
4
5
6
// 语法
{% img [class names] /path/to/image [width] [height] [title text [alt text]] %}
// 实例
{% img full-image /hexo-experiences/PL01.jpg 180 180 hello %}
// 生成的代码
<img src="/blog/hexo-experiences/PL01.jpg" class="full-image" width="180" height="180" title="hello">

值的注意的几点:

- 路径名必须以`/`开始,否则会解析出错
- 路径是相对于`conifg`内的`root`的,这一点挺坑,可以在`source/`下新建一个`uploads`文件夹用于专门放置这些图片资源
1
{\% img hi /uploads/images/test.jpg 100 100 hello hello %}
- 图片宽高只能使用数值,不能包含字符串,也不能是百分数
- 最后一个字段可以为图片添加标题
  1. 引入某个文件中的代码,使用include_code
1
2
3
4
// 语法
{% include_code [title] [lang:language] path/to/file %}
// 实例
{% include_code DOMUtil lang:javascript demo.js %}

值得注意的是:code代码所在的文件必须在downloads/code/目录下,否则无法获取

  1. 引用其他文章的路径,基本功能不大
1
2
3
4
// 语法
{% post_path slug %}
// 实例
{% post_path OS-Brief-Intro %} // >> /blog/2016/05/03/OS-Brief-Intro/
  1. 引用其他文章的链接,用处很大,但是有一个小坑
1
2
3
4
// 语法
{% post_link slug [title] %}
// 实例
{% post_link OS-Brief-Intro 操作系统 %}

小坑:不能放在一段的段首,否则 md 文档或解析错误,出现莫名奇妙的 bug。

  1. 引用文章的资源:获取到的是文章对应asset目录下的资源
1
2
3
4
5
6
7
8
// 语法
{% asset_path slug %}
{% asset_img slug [title] %}
{% asset_link slug [title] %}
// 实例
{% asset_path 01.png %}
{% asset_img 01.png 图片 %}
{% asset_link 01.png 图片 %}
  1. _config.yml文件中的post_asset_folder选项设为true,便可在new一篇新文章的同时创建对应的资源文件夹。引用资源文件夹内的文件请使用13中使用的方法,可以防止首页展示时链接错误的问题。

  2. 链接:数据文件

  3. hexo generate --watch可以监听文件变动,自动generate

  4. hexo g -f可以强制重新生成,防止一些更改后无法generate的清理

  5. 自动提交脚本:deploy.sh

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
hexo generate -f
echo ">>>>>>What is your commit message to blog-material repo?"
read COMMIT1
git add --all
git commit -m "$COMMIT1"
echo "commited"
git push
echo "pushed all to blog-material repo"
cd public
echo ">>>>>>What is your commit message to blog repo?"
read COMMIT2
git add --all
git commit -m "$COMMIT2"
echo "commited"
git push
echo "pushed all to blog repo"
cd ../
  1. 实现 RSS 订阅:hexojs/hexo-generator-feed

  2. Hexo 的markdown解析引擎不支持脚注,可以使用插件实现。

但是笔者在使用了LouisBarranqueiro/hexo-footnotes之后发现hexo server命令无法使用了。(PH:本人是正常的)

  1. 更换默认的 md 渲染引擎(hexo-renderer-marked),改为 hexo-renderer-markdown-it,见配置hexo-renderer-marked-it。几大优点:

    支持脚注解析支持上下标支持emoji – 需要额外配置

2 NexT

  1. NexT 的一些菜单页(如:标签页、分类页、归档页)需要自己添加,方法见链接

  2. NexT 的i18n可以在theme/next/language下的.yml文件下自己定制

  3. NexT 支持文本居中的引用

1
2
{% centerquote %}blah blah blah{% endcenterquote %}
{% cq %} blah blah blah {% endcq %}
  1. NexT 中的图片可以自由地突破容器宽度的限制(扩大26%
1
2
{% fullimage /image-url, alt, title %}
{% fi /image-url, alt, title %}
  1. 在为文章创建 Tags 的时候,避免标签内出现&,否则生成的.xml文件在浏览器端会解析错误,并且订阅功能也会出现故障。

3 主题编写

  1. Hexo 提供的辅助函数中截取一段长文字的前n个字符
1
2
3
4
// swig 的写法
{% truncate('long string', {length: n}) %}
// 实例
{% truncate(post.description, {length:n}) %}
  1. 在 swig 中,胡子或胡子百分号内不能再使用胡子或胡子百分号

  2. DIY 主题,写法参考链接

0%