使用 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%