配置 emacs ox-hugo 包

1 输出文档

#

ox-hugo 全局缺省配置：

• org-hugo-base-dir: markdown 文档根目录，文档会保存到该目录的 contenxt/<HUGO_SECTION> 目录下。

(use-package ox-hugo
  :after ox
  :config
  (setq org-hugo-base-dir (expand-file-name "~/blog/blog.opsnull.com"))
  (setq org-hugo-section "posts")
  (setq org-hugo-front-matter-format "yaml")
  (setq org-hugo-export-with-section-numbers t)
  (setq org-hugo-auto-set-lastmod t))

两种文档输出方式：

1. 建议：One post per Org subtree (preferred)
   • Export only the current post Org subtree, or
   • Export all valid Hugo post subtrees in a loop.
2. 不建议：One post per Org file
   • This works but you won’t be able to leverage Org-specific benefits like tag and property inheritance, use of TODO states to translate to post draft state, =auto weight calculation for pages, taxonomies and menu items, etc.

subtree 模式使用 :PROPERTIES: 来设置 subtree 的输出属性，:PROPERTIES: 必须紧接着 headerline， 中间不能有空行，否则 ox-hugo 可能不识别。

• 一般不需要设置 #:EXPORT_HUGO_WEIGHT: auto，而是依赖 file 级别的参数 #+HUGO_WEIGHT: auto，这样在导出 file 的所有 subtree 时，自动根据 tree 在文件中的位置自动生成 weight。

:PROPERTIES:
:HUGO_BASE_DIR: /~/blog/blog.opsnull.com/
:EXPORT_HUGO_SECTION: rust
:EXPORT_HUGO_BUNDLE: std
:EXPORT_FILE_NAME: index
:EXPORT_DATE: <2024-08-04 Wed 15:14>
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :series '("rust-lang") :series_order 2
:END:

文档输出根目录(即使只 subtree 输出, 也需要在文档整体设置)：

1. 整个文档：#+hugo_base_dir: ~/blog/blog.opsnull.com
2. subtree：:HUGO_BASE_DIR：

文档输出目录（section）：HUGO_SECTION：

• 整个文件：#+hugo_section: posts
• subtree：:EXPORT_HUGO_SECTION: shell

说明（参考：https://ox-hugo.scripter.co/doc/hugo-section/%EF%BC%89%EF%BC%9A

• 如果设置为 / 则表示的是 content/ 目录；
• 如果是 subtree，对于子 tree，可以通过设置 EXPORT_HUGO_SECTION_FRAG 来在父 tree 的路径下添加子目录, 例如：
  • 父 tree 设置 :EXPORT_HUGO_SECTION: a
  • 子 tree 设置 :EXPORT_HUGO_SECTION_FRAG: b, 则子 tree 的输出保存位置 content/a/b

输出文档标题：

• 整个文件：#+titile; (如果要输出整个文档, 则必须要定义);
• subtree: org header 行内容作为输出文档的标题；

输出文件名：

• 整个文件：#+EXPORT_FILE_NAME: index
• subtree：:EXPORT_FILE_NAME: my-first-post, 不能嵌套，必须在 leaf node 上定义, 如果要输出该 subtree, 则必须要定义;

输出 Bundle 文档：

1. Bundle：位于某一个 Section 下的目录名，由 #+HUGO_BUNDLE 配置；
2. 输出文件名：必须是 index，由 #+EXPORT_FILE_NAME: index 配置；
   • 如果未定义 EXPORT_FILE_NAME（不建议）， 则文件名称和源文件名称一致。

示例：

#+HUGO_BASE_DIR: ~/blog/blog.opsnull.com
#+HUGO_SECTION: ebpf
#+,#+HUGO_BUNDLE: linux-tracing-and-ebpf-introduction
#+EXPORT_FILE_NAME: index
#+HUGO_WEIGHT: auto # 根据 subtree 在文档中的位置，自动设置 weight，位置越靠前，weight 越小，越靠前显示

subtree 输出 Bundle 文档：

• Bundle 目录：由 :EXPORT_HUGO_BUNDLE: 指定，不能于整个文档或其他 subtree 重名。
• 输出文档名：由 :EXPORT_FILE_NAME: 指定，但一般为 index 或 _index（建议, 可以使输出文件名唯一）;
  • EXPORT_FILE_NAME 不能嵌套，也即一个子 subtree 不能再定义该 Property；
  • 如果使用 branch/leaf 结构，EXPORT_FILE_NAME 只能用于 leaf nodes, 也即设置 EXPORT_FILE_NAME: index

文档分类和 tag 属性：

1. 整个文档：#+HUGO_TAGS: ebpf，#+HUGO_CATEGORIES: ebpf
2. subtree: 通过 org-mode 的 header tag 来定义，其中分类的 tag 名称使用 @前缀，如 :tag1:@catagory1:
3. 特殊的 noexport tag 表示不输出这个 header 及以下的内容。

输出的 front matter 格式：

1. 整个文档：#+hugo_front_matter_format: yaml
2. subtree：:EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml

Custom Front-matter Parameters:

1. 整个文档: #+hugo_custom_front_matter:
2. subtree: :EXPORT_HUGO_CUSTOM_FRONT_MATTER:

# 文档级别
#+#+HUGO_CUSTOM_FRONT_MATTER: :series '("emacs") :series_order 2

# subtree
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :series '("rust crate") :series_order 1

发布命令：

• 如何区分输出整个文档或 subtree?
  • 如果文档包含 #+titile: 且光标不位于包含 PROPERTY 的 subtree 中, 则表明要输出文档;
  • 如果光标位于包含 PROPERTY 的 subtree 中, 而且具有 EXPORT_FILE_NAME PROPERTY 则输出该 subtree;
  • 即使只输出 subtree, 也需要在全局设置 #+hugo_base_dir: ~/blog/blog.opsnull.com
  • 如果给文档或 subtree 新加了配置, 需要关闭并重新打开文档, 这样才能生效.
• 发布 file 或 subtree：
  • C-c C-e H H: org-hugo-export-wim-to-md
    • If point is in a valid Hugo post subtree, export that subtree to a Hugo post in Markdown
      • 设置了 subtree property：EXPORT_FILE_NAME
    • If the file is intended to be exported as a whole (i.e. has the #+title keyword), export the whole Org file to a Hugo post in Markdown.
  • C-c C-e H A： org-hugo-export-wim-to-md :all-subtrees
    • If the Org file has one or more ‘valid Hugo post subtrees’, export them to Hugo posts in Markdown.
    • If the file is intended to be exported as a whole (i.e. no ‘valid Hugo post subtrees’ at all, and has the #+title keyword), export the whole Org file to a Hugo post in Markdown.
• 只发布 file：
  • C-c C-e H h：Export the Org file to a Hugo post in Markdown. This is same as calling the org-hugo-export-to-md function interactively.

2 hugo front-matter

#

hugo 支持两种 front matter 格式: yaml 或 toml:

• file based

#+hugo_front_matter_format: yaml

subtree based

:PROPERTIES:
:EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml
:END:

输出文章标题： #+title ;

设置输出文件名:

• file base：#+EXPORT_FILE_NAME；
• subtree-base-exported: 需要设置 EXPORT_FILE_NAME;
• 如果配置了 #+hugo_bundle 或者 :EXPORT_HUGO_BUNDLE:, 则使用它作为文章目录名, EXPORT_FILE_NAME 可以设置为 index或 _index;

subtree-based:

file-based-export:

参考：

1. https://ox-hugo.scripter.co/doc/org-meta-data-to-hugo-front-matter/

3 Post Bundle 和 Thumbnail

#

使用 post bundle 可以将一篇文档发布为一个目录，这样后续可以在目录中添加 thumbnail&hero 图片（feature* 开头）或background 图片（background* 开头）。

• EXPORT_HUGO_BUNDLE: 指定 post bundle 的目录名称, 位于 content 目录下的子目录名称。
• EXPORT_FILE_NAME: 建议设置，这样放置源文件重命名后，输出多份，一般是固定的 index；

*  DONE shell 历史 :shell:bash:lang:@lang:blog:
CLOSED: [2023-05-07 Tue 16:10]
:PROPERTIES:
:EXPORT_DATE: [2023-05-07 Thu 15:00]
:EXPORT_HUGO_BUNDLE: 2023-05-07-shell-history
:EXPORT_FILE_NAME: index
:END:

这篇博客分享下 UNIX/Linux shell 的历史。

#+hugo: more

导出结果：

$ ls  2023-05-07-shell-history/
featured.png  images/  index.md
$ ls  2023-05-07-shell-history/images/shell_兼容和历史/
2023-05-07_18-23-36_screenshot.png
$