用 ox-hugo 写博客

2021-05-22

写在前面

ox-hugo 的功能是打通 org-mode -> hugo 的发布渠道，并且提供一个基于 org-mode 的博文管理方式，因此本文的目标读者是日常使用 emacs 写作的人群。

对于正在使用 org-mode 写 hugo 博客但还不了解 ox-hugo 的读者，这里简要介绍一下 ox-hugo 具体解决了什么痛点：

你并不需要修改你的博客，ox-hugo 完全兼容原有模式
ox-hugo 会将 org 文档自动转换成 markdown 格式。这样的好处是可以正常显示表格了（hugo 目前并不支持 org 表格）。
ox-hugo 能自动将 org 文档中的图片保存到 hugo 的相应路径，你可以不用在手动移动图片文件了。比如我想要在博文中插入截屏图片就只需要执行 M-x org-screenshot-take 就可以了， ox-hugo 会帮我完成剩下的事情
你可以像管理 org-mode tree 一样管理博客。比如用 TODO 关键字表示草稿、DONE 表示正式发布，它还会自动更新博客的创建时间和修改时间，非常方便

用一张图看看使用 ox-hugo 之后的写作方式：

从截图中你可以了解到 ox-hugo 的写作特点：

你可以将所有博文放在一个 org 文件中。在右侧的编辑器中，你可以看到除了本篇博客之外，还有其他几篇用 TODO 关键词标识的博客，它们目前都是草稿，而只要切换到 DONE 它们就会正式发布
ox-hugo 使用 properties 来指定 hugo 配置，比如博客发布的路径、标题以及文章摘要等等
ox-hugo 会转换 org-mode TAG 和 emacs 生态完美结合
ox-hugo 提供了一个名为 org-hugo-auto-export-mode ，当你修改文章之后会自动发布到 hugo 中

如何使用 ox-hugo

安装

官方文档上有如何安装的说明，如果和我一样用的是 doom emacs, 那么安装也很简单，首先在 package.el 文件中添加：

(package! ox-hugo)

然后在 config.el 文件中启用即可：

(use-package! ox-hugo
  :ensure t
  :after ox)

快速上手

在将 org 文件导入到 hugo 目录前，还需要配置 Hugo 博客的目录，在 org 文件头中添加如下配置：

#+HUGO_BASE_DIR: ~/Blog/
#+hugo_front_matter_format: yaml
#+hugo_auto_set_lastmod: t
#+HUGO_SECTION: post

指明目录之后执行 M-x org-hugo-export-to-md, 然后就会在 ~/Blog/content/posts/ 目录下生成一个 markdown 文件。

这里简要介绍一下这些配置的意义：

HUGO_BASE_DIR 指定了 hugo 博客文件夹的位置
hugo_front_matter_format 指定了 front matter 的格式
hugo_auto_set_lastmode 会让 ox-hugo 自动更新博客的修改时间
HUGO_SECTION 指定了这篇博客会发布到的目录，比如 post 或者 posts

ox-hugo 提供了两种博客发布方式：基于文件，基于 subtree 。前者将整个 org 文件转换成一个 markdown 文件，而后者可以从一个 org 文件中提取出多个文章。和官方一样我推荐用 subtree 的方式，因为后者功能更为强大，为了简明起见，这里我只介绍后一种。

可能有人会嫌我啰嗦，更愿意从例子中学习，这里我就把这篇博客的原始文件贴上来：

+title: Blog
#+HUGO_BASE_DIR: ~/Blog/
#+hugo_front_matter_format: yaml
#+hugo_auto_set_lastmod: t
#+HUGO_SECTION: post

* TODO 用 ox-hugo 写博客 :emacs:hugo:
:PROPERTIES:
:EXPORT_FILE_NAME: index
:EXPORT_DESCRIPTION: Whole hugo blog in plain text!
:EXPORT_HUGO_BUNDLE: 2021/04/21/how-to-use-ox-hugo
:END:

** 写在前面
   .....
[[file:./images/screenshot-27.png]]
....
** 如何使用 ox-hugo
*** 安装
...

*** 快速上手
...

使用 M-x org-hugo-export-to-md 之后会在 <HUGO_BASE_DIR>/content/<HUGO_SECTION>/<EXPORT_HUGO_BUNDLE> 目录下创建 <EXPORT_FILE_NAME>.md 文件。

如果参考我的例子，你应该就已经学会如何使用 ox-hugo 写博客了。但如果你并不熟悉 hugo bundle, 或者好奇 ox-hugo 会如何处理你的图片，那么请接着看以下的补充说明。

关于 hugo bundle

hugo 官方的文档写得并不是很清晰，反正我看了一头雾水，但经过这么多天的使用，我有了自己的看法，先别问它是什么：

它能做什么？如果你不使用 bundle 那么我相信你会把所有文章放到 post 目录下面，这样时间久了，这个目录下面就会有大量的 md 文件，不便管理。
- 而 bundle 提供了层级目录的功能，你可以像我一样将文章按照年月日的划分放到子文件夹里。
- 不仅如此，你还可以将所有文章相关的资源放到同一个目录下面。比如在以前，文章的图片必须放到 /static/images/ 目录下面，而使用了 bundle 之后，它们就可以放到文章所在的目录下面。
如何使用？
- 还是以我自身情况作为例子，我会先将一篇博客按照年月日划分，然后再加上标题；比如这篇文章是： /2021/04/21/how-to-use-ox-hugo/
- 有了目录之后，再在这个目录下面放置一个 index.md 文件，里面就是博客的正文

希望我上面的说明能够增进你对 hugo bundle 的理解，如果你还是搞不明白它是怎么作用的，可以先按照我的样子进行实验，经过实践想必你会有更好的认识。

关于图片处理

如果不使用 bundle ，那么 hugo 会将图片放到 static/images/ 目录下面，反之，它会将图片放到文章所在的目录下面。

比如，我这篇文章的截图的原始文件路径是 ./images/screenshot-27.png ， ox-hugo 进行转换之后会把它放到 post/2021/04/21/how-to-use-ox-hugo/images/screenshot-27.png 中。

自动发布

每次保存然后手动执行 M-x org-hugo-export-to-md 发布实在太麻烦了，你可以启动 org-hugo-auto-export-mode 来实现自动发布。

目前的体验

一个月前创建了这篇文章，然而直到今天才完成，懒癌发作真是要命啊；不过经过这一个多月的使用体验，我推荐 ox-hugo 也更有底气了，因为它确实方便了博客写作（你甚至可以用 org-agenda 来规划博客写作，设置 Deadline ，任何一个 emacser 都无法抗拒这种诱惑吧 hh)