↓跳过正文

用 emacs 和 ox-hugo 写 blog

·2317 字
Hugo Org-Mode Blog Emacs
目录
emacs-blog - 这篇文章属于一个选集。
§ 1: 安装和配置 blowfish 主题
§ 2: 配置 emacs ox-hugo 包
§ 3: 本文

1 datetime
#

缺省日志格式由 emacs 变量控制： org-hugo-date-format: "%Y-%m-%dT%T%z" ，示例： 2017-07-31T17:05:38-04:00, 这个格式需要与 hugo 的配置的 :EXPORT_DATE: 或 #+DATE 一致, 否则导致输出的文档的创建/修改 meta 数据不能正确显示。

通过设置 #+hugo_auto_set_lastmod: t，ox-hugo 在输出的文档中使用当前 date 来创建或更新 lastmod 字段。

File-based：

Subtree-based Exports：

  1. Date:
  2. CLOSED: [2018-01-23 Tue 14:10]

2.Publish Date

  • SCHEDULED: <2060-01-26 Mon>
  • Expire Date
  • This is set using the :EXPORT_HUGO_EXPIRYDATE: property.
  • Last modified
  • :EXPORT_HUGO_LASTMOD: property.
  • :EXPORT_HUGO_AUTO_SET_LASTMOD: to a non-nil 时 ox-hugo 自动设置该时间戳；
    • 文件级别：#+HUGO_AUTO_SET_LASTMOD: t

EXPORT DATE 必须包含 time, 否则文章不能正确显示创建和更新时间:

:EXPORT_DATE: <2024-08-21 Wed 15:14>

2 image link #

引用 $HUGO_BASE_DIR/static 目录下的图片，如 ~/hugo/static/images/foo.png，发布后 ~/hugo/static 作为根目录, 对下面文件的引用使用 /images/foo.png。

Inline Image（直接显示图片）：

  1. Unhyperlinked（不可点击）： [[/images/org-mode-unicorn-logo-200px.png]]
  2. hyperlinked to an image（可以点击）：=
    =

显示图片链接： [[/images/org-mode-unicorn-logo-200px.png][Click here to see org-mode-unicorn-logo-200px.png]

引用 static 目录外的图片：

  • 如果是位于 static 目录外，且扩展名为org-hugo-external-file-extensions-allowed-for-copying；
  • ox-hugo 会将它们拷贝到 static 目录。
[[~/some-dir/static/images/foo.png]]

如果文件 source path 包含 /static/ 则 ox-hugo 将该文件 copy 到 $HUGO_BASE_DIR/static/ 目录时，会保留源文件路径中 /static/ 后的结构:

如果文件 source path 不包含 /static/ 则会拷贝到 org-hugo-default-static-subdirectory-for-externals 子目录(ox-hugo):

3 detail-summary
#

可以使用 #+details 嵌套的 #+summary 来对一部分内容进行合并和展开：

#+begin_example
#+begin_details
#+begin_summary
Why is this in green?
#+end_summary

#+end_details
#+end_example

效果如下：

Why is this in green?

You will learn that later below in section.

4 summary
#

添加文章总结，在 list 页面显式。

注意：summary 中不能包含链接，否则 hugo 在 list 页面以 card 显示时，格式有问题。

  1. 文件级别：在正文前使用 #+hugo: more 标记来分割 summary 和正文。
  2. subtree 级别：

:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :summary “这篇博客分享下 UNIX/Linux shell 的历史。这篇博客分享下 UNIX/Linux shell 的历史。这篇博客分享下 UNIX/Linux shell 的历史。"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :showSummary true

5 Tags and Categories
#

File-base-exports:

  1. #+hugo_tags: tag1 tag2
  2. #+hugo_categories: cat1 cat2
  3. 统一: #+filetags
    • #+filetags: tag1 tag2
    • #+filetags: @cat1 @cat2

Subtree-base-exports:

  • EXPORT_HUGO_TAGS
  • EXPORT_HUGO_CATEGORIES
  • tags:header line 上的 org tag,如 :tag1:tag2:
  • categories: header line 上的 @ 开头的 tag,如 :@cat1:@cat2:

注：文件级别的 tags、categories 会被所有 subtree 继承。

6 不输出指定 header 下的内容
#

  1. 默认由变量 org-export-exclude-tags 指定的 tags 来控制;
  2. 可以在文件级别或者特定 header section 级别打上 noexport tag.

7 author
#

指定多个 #+author 来指定多个作者：

#+author: FirstName LastName
#+author: FAuthor1 LAuthor1
#+author: FAuthor2 LAuthor2

或者使用 PROPERTY 格式，逗号分割：

:PROPERTIES:
:EXPORT_AUTHOR: FAuthor1 LAuthor1, FAuthor2 LAuthor2
:END:

不输出 author：

#+options: author:nil

:PROPERTIES:
:EXPORT_OPTIONS: author:nil
:END:

blowfish 不显示 Author：

  • Article 设置：showAuthor: false

8 series
#

先定义一个 series taxonomies

[taxonomies]
  tag = "tags"
  category = "categories"
  author = "authors"
  series = "series"

export 后生成的 Mark Articles

series: ["Documentation"]
series_order: 11

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

然后可以通过 http://localhost:1313/series/ 来访问。

Marking an article as part of a series will automatically display the series module as you see in this page for example. You can choose whether that module starts opened or not using the article.seriesOpened global variable in params.toml or the front-matter parameter seriesOpened to specify an override at the article level.

9 org tree properties
#

CLOSED: [2023-05-07 Sun 16:10]

:PROPERTIES:
:EXPORT_DATE: [2023-05-07 Sun 15:00]
:HUGO_BASE_DIR: ~/blog/blog.opsnull.com
:EXPORT_HUGO_SECTION: rust
:EXPORT_FILE_NAME: clap
:EXPORT_HUGO_BUNDLE: clap
:EXPORT_FILE_NAME: index
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :series ‘(“rust crate”) :series_order 1
# 生成目录结构
:EXPORT_HUGO_MENU: :menu “main”
# 生成各种 key:value, key 用 : 开头;
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :foo bar :baz zoo :alpha 1 :beta “two words” :gamma 10
:END:

10 保存时自动导出
#

M-x org-hugo-auto-export-mode

11 Custom Front-matter Parameters
#

Custom Front-matter Parameters 是对 hugo 没特殊意义，但是对 theme 有意义的配置：

  • subttee: :EXPORT_HUGO_CUSTOM_FRONT_MATTER: property
  • file： #+hugo_custom_front_matter:

subtree： 如果是多行的化，第二个 MATTER 开始的后面加 +。

:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :key1 value1 :key2 value2  # 一行可以设置多个 key value
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :key2 value2
:END:

file：

#+hugo_custom_front_matter: :key1 value1
#+hugo_custom_front_matter: :key2 value2

list 语法：

:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :animals '(dog cat "penguin" "mountain gorilla") # list 语法
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :integers '(123 -5 17 1_234)
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :floats '(12.3 -5.0 -17E-6)
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :booleans '(true false)
:END:

输出：

animals = ["dog", "cat", "penguin", "mountain gorilla"]
integers = [123, -5, 17, 1_234]
floats = [12.3, -5.0, -1.7e-05]
booleans = [true, false]

Map 语法：

:PROPERTIES:
:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :versions '((emacs . "27.0.50") (hugo . "0.48"))
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :header '((image . "projects/Readingabook.jpg") (caption . "stay hungry, stay foolish"))
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :collection '((animals . (dog cat "penguin" "mountain gorilla")) (integers . (123 -5 17 1_234)) (floats . (12.3 -5.0 -17E-6)) (booleans . (true false)))
:END:

输出：

[versions]
  emacs = "27.0.50"
  hugo = 0.48
[header]
  image = "projects/Readingabook.jpg"
  caption = "stay hungry, stay foolish"
[collection]
  animals = ["dog", "cat", "penguin", "mountain gorilla"]
  integers = [123, -5, 17, 1_234]
  floats = [12.3, -5.0, -1.7e-05]
  booleans = [true, false]

其他 map of map，可以使用 Extra front-matter。

配置 subtree 属性：

  • TOML （默认）：:EXPORT_HUGO_FRONT_MATTER_FORMAT: toml；
  • YAML： :EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml
  • 具体选 TOML 和 YAML 需要和 ox-hugo 导出时设置的 front matter 格式一致：
    • emacs 变量 org-hugo-front-matter-format 配置。

,#+begin_src yaml :front_matter_extra t
foo:
  - bar: 1
    zoo: abc
  - bar: 2
    zoo: def
,#+end_src

YAML 格式：

,* Post with YAML front-matter
:PROPERTIES:
:EXPORT_FILE_NAME: extra-front-matter-yaml
:EXPORT_HUGO_FRONT_MATTER_FORMAT: yaml
:END:
The contents of the #+begin_src yaml :front_matter_extra t YAML
block here will get appended to the YAML front-matter.
,#+begin_src yaml :front_matter_extra t
foo:
  - bar: 1
    zoo: abc
  - bar: 2
    zoo: def
,#+end_src

blowfish theme 自定义的 front-matter 参数列表: https://blowfish.page/docs/front-matter/

示例:

:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :summary "这篇博客分享下 UNIX/Linux shell 的历史。这篇博客分享下 UNIX/Linux shell 的历史。这篇博客分享下 UNIX/Linux shell 的历史。"
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :showSummary true
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :series '("shell") :series_order 1

参考：https://ox-hugo.scripter.co/doc/custom-front-matter/

12 中文支持
#

导出时去掉文档中间的空格。

The locale is manually set to Chinese or Japanese by setting it to zh or ja using #+hugo_locale: keyword (or EXPORT_HUGO_LOCALE property).

file 级别：

#+HUGO_LOCALE: zh

subtree 级别：

:EXPORT_HUGO_LOCALE: zh

13 menu front-matter #

So on each Page, the user can specify the keys of the associated Menu Entry using the menu front-matter.

In Org mode, these Menu Entry keys are specified using the :EXPORT_HUGO_MENU: property (subtree-based exports) or #+hugo_menu: keyword (file-based exports). They are set in this property list form:

:EXPORT_HUGO_MENU: :menu <menu name> <:key 1> <val 1> <:key 2> <val 2> ..

The :menu key is mandatory because that’s used to specify the current Page’s Menu Entry’s parent Menu name.

  • menu name 两个类型：main 和 footer，分别表示页面头部和底部的导航。

例如：

  • 未指定 :parent 时，直接添加到 main 菜单栏中, 指定时 value 应该是父 menu 的 Name 或 Identifier 值。
  • 未指定 :name 时，默认使用文档标题, 如 :EXPORT_FILE_NAME: 设置的值;
  • :identifier : 如果多个菜单项名称相同, 则需要配置该参数来区分. 如果未设置则默认为 :title 值;
  • :title : 默认为文档标题;

#+,#+hugo_menu: :menu main :parent emacs

例如:

,* Posts under the main Menu
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu main
:END:
,** Post 1
:PROPERTIES:
:EXPORT_FILE_NAME: post-1
:END:
,** Post 2
:PROPERTIES:
:EXPORT_FILE_NAME: post-2
:END:

产生的 menu 如下:

[menu]
  [menu.main]
    weight = 3001
    identifier = “post-1” # 来源于文档标题, 进而来源于 :EXPORT_FILE_NAME:

[menu]
  [menu.main]
    weight = 3002
    identifier = “post-2”

另一个例子:

,* Parent subtree
:PROPERTIES:
:EXPORT_HUGO_MENU: :menu “something here” :parent posts
:END:
,** Post 1
:PROPERTIES:
:EXPORT_FILE_NAME: foo
:EXPORT_HUGO_MENU_OVERRIDE: :identifier “abc” :weight 100
:END:
,** Post 2
:PROPERTIES:
:EXPORT_FILE_NAME: bar
:EXPORT_HUGO_MENU_OVERRIDE: :weight 1
:END:

输出:

[menu]
  [menu."something here"]
    parent = "posts"
    weight = 100
    identifier = "abc"

[menu]
  [menu."something here"]
    identifier = "post-2"
    parent = "posts"
    weight = 1

file-based 的带 parent ment 的例子：

#+hugo_menu: :menu main :parent Emacs

参考：https://ox-hugo.scripter.co/doc/menu-front-matter/

注意：如果在 config/_default/menus.zh-cn.toml 中定义了 menu entry，则 Name 不能与 content/{section}/_index.md 中定义的 menu::main::name 重复，可以删除后续 menu 项目的定义。

14 weight
#

可以为 file 或 subtree 指定 weight ，值越小，在 list 页面显示的越靠前。

同时也可以先在 file 级别设置 weight 为 auto，这样会自动为 subtree 设置 weight，位置越靠前，weight 越小。

file 设置：

#+HUGO_WEIGHT: auto # -1

subtree 设置：

:EXPORT_HUGO_WEIGHT: auto
emacs-blog - 这篇文章属于一个选集。
§ 1: 安装和配置 blowfish 主题
§ 2: 配置 emacs ox-hugo 包
§ 3: 本文

相关文章

安装和配置 blowfish 主题
·3247 字
Hugo Org-Mode Blog Emacs
安装和配置 Hugo blog 的 blowfish 主题
配置 emacs ox-hugo 包
·2200 字
Hugo Org-Mode Blog Emacs
配置 emacs 使用的 ox-hugo 包，支持自动导出 blog md 文档
magit
··8481 字
Emacs Emacs
magit 是最好用的 git 客户端!
My Emacs Dotfile
··19856 字
Emacs

Emacs 是 Hacker 的一种生活方式，而这是符合我口味的私人定制。