title: 关联 GitHub, 让 Hexo 支持查看文章更新历史
date: 2016-01-10 22:38:01
categories:
- 术业专攻
tags:
- Hexo
- GitHub
permalink: hexo-post-version-control
---

<h2 id="intro">前言</h2>Hexo 的文章源文件就是一个个 Markdown 文本，自己一直把这些文件备份在 [GitHub][1] 上。渐渐发觉，如果只把 GitHub 当作普通网盘，那真是有点大材小用了。于是稍作折腾，成功地把 GitHub 上的备份关联到主题中。现在，在文章文末版权区，可以很方便地跳转查看文章更新记录、历史版本以及下载源文件。

<!-- more -->

![version-control](/resources/version-control.png)

## 文件处理
### 文件命名
- 为了便于文章识别和自动关联文件，文章 Markdown 的文件名应该符合规范。
- 建议使用 文章建立日期.固定链接 `YY-MM-DD.permalink.md` 的形式。
- 在文章 [Front-matter] 中设置固定链接 permalink，然后填写文件名，例如本文完整文件名为 `2016-01-10.hexo-post-version-control.md`
- 为什么不使用文章标题作为文件名:
> 一是因为标题偶尔会变动，修改相对麻烦；二是标题可能包含不能用作文件名的符号，导致关联出错。

### 文件备份
- 把 `hexo/sources/_posts` 文件夹同步备份到你的 GitHub 上，不熟悉 Git 的可使用 GitHub Desktop 操作，具体方法自行搜索。

## 代码添加
把下面 EJS 代码添加到主题文章模板合适位置中，[Yelee][2] 主题是添加在文末版权区中。参考备份文件在 Github 的链接修改前半部分地址。

{% codeblock yelee/layout/_partial/post/nav.ejs lang:erb https://github.com/MOxFIVE/M-Hexo-Blog/commit/d8a4942dab23920837cc70249c31697d36e49235 Post Version Control %}
<% if (post.backup != false){ %>
    <p>
        <span>更新历史:</span><i class="fa fa-github"></i>
        <a href="<文章 Blame 地址>/<%= post.date.format("YYYY-MM-DD") %>.<%= post.slug %>.md" title="顺序查看文章各部分修改记录" target = "_blank">Blame</a>,
        <a href="<文章 History 地址>/<%= post.date.format("YYYY-MM-DD") %>.<%= post.slug %>.md" title="查看文章有关更新记录" target = "_blank">History</a><span class="raw">文本模式:</span><i class="fa fa-file-text-o"></i>
        <a href="<文章 Raw 地址>/<%= post.date.format("YYYY-MM-DD") %>.<%= post.slug %>.md" title="查看 & 下载文章 Markdown 原始文本" target = "_blank"> .md Raw</a>
    </p>
<% } %>
{% endcodeblock %}

## 代码简析

``` erb
<!-- 不设置 backup: false 则默认显示 -->
<% if (post.backup != false){ %>
    <p> 
        <span>更新历史:</span><i class="fa fa-github"></i>
        <!-- 不同功能替换前面超链接即可，文件名不变 -->
        <!-- 文件名生成: <%= post.date.format("YYYY-MM-DD") %>.<%= post.slug %> -->
        <a href="<文章 Blame 地址>/<%= post.date.format("YYYY-MM-DD") %>.<%= post.slug %>.md" title="顺序查看文章各部分修改记录" target = "_blank">Blame</a>,
        <a href="<文章 History 地址>/<%= post.date.format("YYYY-MM-DD") %>.<%= post.slug %>.md" title="查看文章有关更新记录" target = "_blank">History</a><span class="raw">文本模式:</span><i class="fa fa-file-text-o"></i>
        <a href="<文章 Raw 地址>/<%= post.date.format("YYYY-MM-DD") %>.<%= post.slug %>.md" title="查看 & 下载文章 Markdown 原始文本" target = "_blank"> .md Raw</a>
    </p>
<% } %>
```

### Blame
- 顺序列出文章内容，左侧显示各部分 commit 信息，最后修改时间等。
![Blame](/resources/Blame.png)

### History
- 列出与该文件相关的更新记录 (commit)，按路径匹配。我一般直接就用提交时间作为 commit 信息了，想要更直观查看变动的可以在提交时书写更完善的 commit 信息。

![History](/resources/History.png)

### .md Raw
- 在线查看或者直接下载文章原始 Markdown 文本。
![Raw](/resources/Raw.png)

## 后记
> - 这是半自动的版本控制，需要手动把文章同步备份到 GitHub；
> - 代码部分的变动基于 [Yelee][2] 主题，其它主题用户可以参考 [另一篇文章][3] 的方法，自行添加代码到合适位置；
> - 小图标来自 Font Awesome，需主题支持才会正常显示；
> - 本文不详解 Hexo 基础知识，有设置项不理解的请先阅读 [Hexo 官方帮助文档][4]。

[1]: https://github.com/MOxFIVE/Markdown-Archives-Backup
[2]: https://github.com/MOxFIVE/hexo-theme-yelee
[3]: /2015/10/25/hexo-tag-cloud/
[4]: https://hexo.io/zh-cn/docs/



## 相关链接
1. **GitHub Desktop**: <https://desktop.github.com/>
1. **Font Awesome**: <http://fontawesome.io/>
1. **Hexo 使用文档**: <https://hexo.io/zh-cn/docs/>
1. ***Hexo 文章版本控制***  by **MOxFIVE** on <code>2016/01/10</code>: <https://github.com/MOxFIVE/M-Hexo-Blog/commit/d8a4942dab23920837cc70249c31697d36e49235>