↓Skip to main content
  1. Posts/

把博客从 Hexo 迁移到 Hugo

··3194 words·7 mins·
Blog Hugo Hexo MathJax LaTeX Pandoc Markdown
Table of Contents

这个博客于 2017 年 2 月开始搭建运行，最初使用的是 Hexo 搭建，配合精美的 NexT 主题，经过鼓捣，差不多算是做出了让自己满意的博客。不过每次安装 Hexo，要配置的东西太多了，总觉得不是很简洁，另外，随着文章数量的增加，Hexo 生成博客的速度也慢了下来。怀着尝鲜的心态，我把 Hexo 博客迁移到了 Hugo。

Hugo 安装与配置
#

Hugo 安装
#

首先安装 Hugo，在不同系统上安装都很简单，在 Mac 上，使用 Homebrew 可以安装 Hugo：

brew install hugo

建立博客站点
#

安装以后，首先我们需要建立一个博客目录，下面存放的是博客的所有配置以及博文等资料，例如要建立一个名为 Blog 的站点，使用下面的命令：

hugo new site Blog

会看到以下提示内容：

Congratulations! Your new Hugo site is created in /Users/jdhao/Blog.

Just a few more steps and you’re ready to go:

  1. Download a theme into the same-named folder. Choose a theme from https://themes.gohugo.io/, or create your own with the “hugo new theme ” command.
  2. Perhaps you want to add some content. You can add single files with “hugo new /.”.
  3. Start the built-in live server via “hugo server”.

Visit https://gohugo.io/ for quickstart guide and full documentation.

建立站点以后，博客根目录下默认有这些文件和子目录：

archetypes/  config.toml  content/     data/        layouts/     static/      themes/

config.toml 就是博客的配置文件，archetypes 目录下有一个 default.md，存放的是建立新博文时候默认使用的模板，可以根据自己需求修改。content 目录用来存放博文，static 可以存放一些自己的文件，themes 文件夹用于存放不同的主题。

安装主题
#

建立站点以后，我们需要安装主题，Hugo 提供了一个主题浏览网站，可以浏览各种主题的效果，找了一圈，没有发现自己特别中意的。也可以直接在 GitHub 上搜索 Hugo 的主题，最后经过各种查找比较，选择了 even 主题。

在博客根目录下，使用以下命令安装 even 主题：

git init
git submodule add https://github.com/olOwOlo/hugo-theme-even.git themes/even

然后编辑 config.toml，设置主题为 even:

theme = "even"

新建博文
#

要建立新的博文 test.md，使用下面的命令：

hugo new post/test.md

这个命令会在 content 目录下建立 post 目录，并在 post 下生成 test.md 文件，博文书写就在这个文件里使用 Markdown 语法完成。博文的 front matter 里 draft 选项默认为 true，需要改为 false 才能发表博文，建议直接更改上面说的archetypes 目录下的 default 文件，把 draft: true 改为 draft: false，这样生成的博文就是默认可以发表的。

和 Hexo 一样，在 front matter 里面，使用 tags 指定文章的 tag，使用 categories 指定文章的类别，示例如下：

tags: [LaTeX, Hexo, font]
categories: [Mac, Linux]

把 Hexo 博客里的所有博文 Markdown 文件拷贝到 content/post/ 目录下，就完成了博文的迁移。

查看生成效果
#

为了查看生成的博客的效果，可以使用 hugo server 命令，示例输出如下：

                   | EN
+------------------+-----+
  Pages            | 196
  Paginator pages  |   9
  Non-page files   |   0
  Static files     |  63
  Processed images |   0
  Aliases          |  53
  Sitemaps         |   1
  Cleaned          |   0

Total in 90 ms
Watching for changes in /Users/jdhao/Blog/{content,data,layouts,static,themes}
Watching for config changes in /Users/jdhao/Blog/config.toml
Serving pages from memory
Running in Fast Render Mode. For full rebuilds on change: hugo server --disableFastRender
Web Server is available at http://localhost:1313/ (bind address 127.0.0.1)
Press Ctrl+C to stop

博客有七十多篇文章，生成时间才 90 ms，速度果然惊人。该命令会建立一个本地的博客服务器，直接在浏览器访问网址 http://localhost:1313/ 即可查看生成的博客效果。

部署到 github pages
#

确定生成的博客效果无误后，就可以将博客部署到服务器了，我使用的是免费的 GitHub pages 服务。本部分假定我们在 github pages 建立的是 User/Organization Pages ，地址名称形式为https://<USERNAME|ORGANIZATION>.github.io/，如果不是这种类型地址，请参考 Hugo 官方指导。

如果之前已经建立了 xxxx.github.io 这种形式的仓库，并且使用 Hexo 往这个仓库部署过，但是不想要之前的东西了，在博客的根目录下，运行下面的命令即可：

mkdir public
cd public
git init
git remote add upstream https://github.com/jdhao/jdhao.github.io.git

执行 hugo -t even，hugo 会生成 blog 内容，放到 public 目录。然后，我们把 public 下面的内容 push 到 github 即可。

git add .
git commit -m  "switch to hugo"
git push -f upstream master # 第一次 push 必须使用 -f，因为此时远程仓库非空，和本地有冲突

这样就部署成功了，一般等待几分钟，访问自己的博客，就能看到更新以后的内容。

每次部署都输入一大堆命令，很繁琐，参考官方教程，做一个 deploy.sh 脚本，方便每次把博客 push 到 github。我的 deploy.sh 脚本内容为：

点击查看脚本内容。
#!/bin/bash

echo -e "\033[0;32mDeploying updates to GitHub...\033[0m"

# build the project
hugo -t even

cd public

git add .

msg="rebuilding site `date`"

if [ $# -eq 1 ]
  then msg="$1"
fi

git commit -m "$msg"

# push source to github

git push upstream master

# come back to blog root

cd ..

赋予 deploy.sh 文件执行权限：

chmod u+x deploy.sh

以后执行 ./deploy.sh 就可以部署博客到 github 了。

注：第一次 push 需要使用 -f，以后 push 就不需要该参数了，force push 以后，github 仓库的 commit 数量会清零，原有的 commit 信息会丢失，不过这个仓库就是为了存放博客，不需要和其他人合作，所以 commit 信息丢失问题不大。

主题设置与迁移细节
#

时间格式
#

Hexo 中时间格式与 Hugo 格式不太相同，Hugo 对时间格式的要求比较严格，Hexo 中YYYY-MM-DD HH:MM 格式的时间在 Hugo 中无法被正确识别。Hugo 中使用的时间格式如下：

YYYY-MM-DD HH:MM:SS +0800

最后的 +0800 代表中国的时区是GMT+8。

另外，Hexo 中 front matter 代表博客更新时间的 updated 选项在 Hugo 中是 lastmod。

具体时间格式的替换，我采用 Sublime Text 配合正则表达式匹配来替换。

文章的 permalinks 设置#

Hexo 中，文章的链接都是 YYYY/MM/DD/post_name/ 的格式，在 Hugo 中，可以通过设置 permalinks 参数来实现平滑过渡，在 config.toml 中加入以下设置：

[permalinks]
  post = "/:year/:month/:day/:filename/"

大小写问题
#

Hugo 默认会把 url 中的大写字符转为小写，如果不想转换，在配置文件中加入

disablePathToLower = true

Hugo 默认会把分类（categories）名称转为小写，如果不想转换，在配置中加入，

preserveTaxonomyNames = true

如何完美支持 LaTeX 公式
#

由于 Markdown 中的 \，_ 等字符在 LaTeX 公式也有特殊含义，两者会有冲突，之前为了配置 Hexo 博客的数学公式支持也费了很大功夫，具体过程可以参考这篇博客。迁移到Hugo以后，经过搜索、查找与验证，找到了两种比较好的解决方法。

2022-03-04 注：mmark 已经被 hugo 淘汰，后续会移除支持，不再推荐。

### 使用 mmark 格式

Mmark 是一个 Markdown 引擎，Hugo 原生支持。对于包含 LaTeX 公式的文档，首先把后缀名改为 mmark（即名称由 *.md –> *.mmark），然后在文章的 front matter，加上一行设置

markup: mmark

使用 Pandoc
#

Hugo 也支持使用外部的处理程序来处理 Markdown 文件，例如 asciidoc，reStructuredText 和 Pandoc。这里选择 Pandoc，首先安装Pandoc。然后在文章的 front matter，加上一行设置

markup: pandoc

hugo 在生成博客的时候就会自动调用 pandoc 来生成 html。

小问题
#

Hugo 中，为了支持 LaTeX，如果使用 mmark 或者 pandoc 来处理 Markdown，生成的博客没有目录。对于 mmark 格式，暂时不支持目录；对于Pandoc，无法生成 TOC 是因为 hugo 在调用 Pandoc 将 Markdown 文件转换为 HTML 的时候，只使用了 --mathjax 选项，没有使用 --toc 选项，具体 code 见 这里, 如果加上 --toc 选项应该是可以生成 TOC 的。不妨试着加上 --toc 选项，然后 自己编译hugo看看能不能生成 TOC。

参考
#

文章缩略的格式
#

要在文章某个地方缩略，要使用 <!--more-->。注意 more 的周围不要有空格，Hugo无法识别这种有空格的缩略格式，这里的记录也证实了这个情况。同时，也可以参考Hugo 官方文档的说明。

个人文件的位置
#

如果博客中有一些文章设定了下载链接，建议把文件放在博客根目录下的 static 目录，可以在该目录下建立名为 files 的目录（该名称仅仅是举例，可以根据自己喜好更改），然后把文件放在 files 目录下。假如 files 目录下有一个文件 test.pdf，参考这里，在博客中引用它的正确方式是:

[点击这里下载 test.pdf](/files/test.pdf)

完整的配置文件见这里。

busuanzi 博客计数失效？
#

Even 主题默认使用 busuanzi 服务来给博客的 pv 和sv 计数，最近打开博客，发现计数部分的数字无法显示，一直在转圈。查了一下，原来是busuanzi 在七牛云上的域名失效了，所以服务挂了。

解决办法如下，打开 even 主题的目录，打开主题目录下/layouts/partials/head.html 这个文件，把1

<script async src="//dn-lbstatics.qbox.me/busuanzi/2.3/busuanzi.pure.mini.js"></script>

改为

<script async src="//busuanzi.ibruce.info/busuanzi/2.3/busuanzi.pure.mini.js"></script>

然后重新生成博客，部署到博客托管网站服务器即可。

参考
#

  1. 如何快速定位到这个文件，参考这篇文章 ↩︎

Related

Hexo 书写 LaTeX 公式时的一些问题及解决方法
··1169 words·3 mins
Blog Hexo LaTeX NexT Markdown MathJax Pandoc
LaTeX Equation Numbering Done Right in Hexo
··678 words·4 mins
Blog Hexo LaTeX MathJax NexT Markdown
How to Install Hexo and Theme NexT from Scratch on Windows
··1218 words·6 mins
Blog Markdown NexT Hexo LaTeX Pandoc