ox-hugo用法
2023年11月11日 2023年11月17日
便签
介绍
Hugo, 或者gohugo, 是用Go语言编写的, 提供生成静态博客内容功能的一个软件
ox-hugo
, Emacs插件, 用以生成Hugo兼容的Markdown文件
说明
有两个范畴: 一个org文件对应一篇文章; 一个org子树对应一篇文章. 对应两种设置域: org文件选项和子树属性
以一个org文件对应一篇文章作为基础
org文件选项设置
必须设置的选项
- HUGO_BASE_DIR
导出目录的根目录. 导出文件存放在其下级目录, 且是下级content目录下. 如果content目录不存在, 自动创建
如果HUGO_BASE_DIR的值为/Volumes/Blogs, 那么无其他设置时, 导出文件存放在/Volumes/Blogs/content目录下
根目录/content - HUGO_SECTION
导出目录的下级目录. 和HUGO_BASE_DIR一起决定导出文件所在目录
如果HUGO_BASE_DIR的值为/Volumes/Blogs, 而HUGO_SECTION的值为Hobby, 导出文件存放在/Volumes/Blogs/content/Hobby目录下
根目录/content/分区目录 - TITLE
导出org文件时, TITLE选项用作标题, 导出文件和org文件同名. 如果使用临时buffer, 则需要输入导出文件名
根目录/content/分区目录/文章标题.md
文本图片
- ox-hugo支持把文章内图片迁移拷贝到导出目录, 需满足以下条件:
- 使能org-hugo-external-file-extensions-allowed-for-copying
- 根目录下有static文件夹
- 使能org-hugo-external-file-extensions-allowed-for-copying
- 并做以下事情:
- 在static目录下创建ox-hugo文件夹
- 把图片拷贝到static/ox-hugo文件夹
- 在static目录下创建ox-hugo文件夹
对于图片和博文都不多的博客, 这一实现无疑提供了便利
相对应地, 如果博客图片较多, 后续出现整理博客的需求, 则无法使用任何分类
建议安装时禁用org-hugo-external-file-extensions-allowed-for-copying, 自行管理图片
1(setq org-hugo-external-file-extensions-allowed-for-copying nil)
示例
1#+HUGO_BASE_DIR: /Volumes/Blogs 2#+HUGO_SECTION: Hobby 3#+TITLE: 示例
以下写法也是可以的
1#+HUGO_BASE_DIR: ../
1#+HUGO_SECTION: ./
常用选项
Markdown文件选项格式
toml
1#+HUGO_FRONT_MATTER_FORMAT: toml
yaml
1#+HUGO_FRONT_MATTER_FORMAT: yaml
文章权重
通常用于同级目录文章显示时排序
设定给定值
1#+HUGO_WEIGHT: 10
文章状态
值可以为true或false. 和hugo构建时使用的命令相对应: 如果值为true, 则说明文章仍是草稿, 未指定其他选项构建时, 文章不会被包含到生成的静态博客内容中
1#+HUGO_DRAFT: true
创建时间
和hugo构建时使用的命令相对应: 如果未指定其他选项, 会比对文件创建时间和某个时区的时间. 若晚于该时区时间, 文章不会被包含到生成的静态博客内容中
和hugo本地测试的命令相对应: 如果未指定其他选项, 会比对文件创建时间和某个时区的时间. 若晚于该时区时间, 文章不会被展示
1#+DATE: 2023-08-21T09:42:45
有自动填写的方法
记录最后修改时间
导出时, 自动填写该文章最后修改时间
1#+HUGO_AUTO_SET_LASTMOD: t
文章分类和标签
1#+HUGO_CATEGORIES: emacs org 2#+HUGO_TAGS: hugo
自定义选项
导出后的博文, 在不同的主题中展示. 主题会定义自己的选项, 个性化展示
1#+HUGO_CUSTOM_FRONT_MATTER: :foo bar :baz zoo
导出后:
1foo = bar 2baz = zoo
子树属性设置
既是进阶级用法, 也是ox-hugo所推荐的用法
当文章数较多时, 单个文章的导出将变得繁琐
子树可以使用文件的以下选项
1#+HUGO_BASE_DIR: ../ 2#+HUGO_SECTION: ./ 3#+HUGO_AUTO_SET_LASTMOD: t 4#+HUGO_DRAFT: false 5#+HUGO_FRONT_MATTER_FORMAT: yaml
导出子树时可以指定文件名, 子树名作为标题
1:PROPERTIES: 2:EXPORT_FILE_NAME: 导出文件名 3:END:
子树可以更细致地对文章分区
1:PROPERTIES: 2:EXPORT_HUGO_SECTION_FRAG: game 3:END:
- 一个常用结构: 目录是不会导出的, 待导出子树之间同级
1#+HUGO_BASE_DIR: ../ 2#+HUGO_SECTION: ./ 3* 目录 4 :PROPERTIES: 5 :EXPORT_HUGO_SECTION_FRAG: sub 6 :END: 7** 待导出子树1 8 给出导出选项 9** 待导出子树2 10 给出导出选项
均导出到content/sub目录下 - EXPORT_HUGO_SECTION_FRAG支持叠加
manual
1#+HUGO_BASE_DIR: ../ 2#+HUGO_SECTION: ./ 3 4* Main section 5 :PROPERTIES: 6 :EXPORT_HUGO_SECTION: main 7 :END: 8 导出目录为content/main/ 9** Sub section 1 10 :PROPERTIES: 11 :EXPORT_HUGO_SECTION_FRAG: sub1 12 :END: 13 导出目录为content/main/sub1 14*** Sub section 1.1 15 :PROPERTIES: 16 :EXPORT_HUGO_SECTION_FRAG: p1 17 :END: 18 导出目录为content/main/sub1/p1 19*** Sub section 1.2 20 :PROPERTIES: 21 :EXPORT_HUGO_SECTION_FRAG: p2 22 :END: 23 导出目录为content/main/sub1/p2 24** Sub section 2 25 :PROPERTIES: 26 :EXPORT_HUGO_SECTION_FRAG: sub2 27 :END: 28 导出目录为content/main/sub2
可以使用EXPORT_HUGO_SECTION
有EXPORT_HUGO_SECTION_FRAG, 不需要用到EXPORT_HUGO_SECTION
常用选项
Markdown文件选项格式
toml
1:PROPERTIES: 2:EXPORT_HUGO_FRONT_MATTER_FORMAT: toml 3:END:
yaml
1:PROPERTIES: 2:EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml 3:END:
文章权重
设定给定值
1:PROPERTIES: 2:EXPORT_HUGO_WEIGHT: 4 3:END:
导出时自动计算
1:PROPERTIES: 2:EXPORT_HUGO_WEIGHT: auto 3:END:
文章状态
草稿
1* TODO 待导出子树
已完成
1* DONE 待导出子树1 2* 待导出子树2
创建时间
1:PROPERTIES: 2:EXPORT_DATE: 2023-08-21T10:10:05 3:END:
记录最后修改时间
1:PROPERTIES: 2:EXPORT_HUGO_AUTO_SET_LASTMOD: t 3:END:
文章分类和标签
1* 待导出子树 :@分类:标签1:标签2:
自定义选项
如果同时在子树和文件配置，导出子树时，只有子树定义项
1* 每棵子树作为一篇博文 2 :PROPERTIES: 3 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: :foo bar :baz zoo 4 :END:
使用Emacs函数自动填充信息
1title = "`(cdr (assoc "ITEM" (org-entry-properties)))`" 2date = "`(format-time-string "%Y-%m-%dT%H:%M:%S")`"
