hugo org-mode

org-mode 选择

• hugo 本身支持 org-mode，但是相对支持的功能比较少。
• hugo 可以使用 emacs-easy-hugo, 单个文件的去实现。
• hugo 也可以使用 ox-hugo，支持单个 org 文件生成多个 md 文件。

建议使用 ox-hugo 来进行编辑和管理。 可以使用 emacs-easy-hugo 来查看。

安装

在 emacs 的配置文件中添加如下：

(use-package ox-hugo
  :ensure t   ;Auto-install the package from Melpa
  :pin melpa  ;`package-archives' should already have ("melpa" . "https://melpa.org/packages/")
  :after ox)

安装过程中，可能会出现找不到 ox-hugo 某个版本的包，那就需要使用 M-x list-packages 列出文件包，然后 C-s 来查找 ox-hugo，找到之后，点击安装即可。

参考:

Installation
https://ox-hugo.scripter.co/doc/installation/

简单验证

• 创建 content-org 文件夹，然后添加 all-posts.org 文件，在文件中添加如下内容:

#+hugo_base_dir: ../

* My first post                                             :tag1:@category1:
:PROPERTIES:
:EXPORT_FILE_NAME: my-first-post
:END:
This is my post body

• 在 My first post 这一行使用 S-left 设定为 DONE
• 保存后，C-c C-e H H 就会在 content/posts 中生成 md 文件
• hugo server -D 就可以直接看结果了。

参考:

Quick Start
https://ox-hugo.scripter.co/doc/quick-start/

设定输出目录

默认设置

如果没有特别设定，默认的输出目录是由 org-hugo-default-section-directory 来决定，即 content/posts

文件整体设定

• 如果设定 #+hugo_section: articles，输出为 content/articles/
• 如果设定 #+hugo_section: posts/articles，输出为 content/posts/articles/

subtree 设定 EXPORT_HUGO_SECTION

:EXPORT_HUGO_SECTION: 这个值本身是会互相覆盖的，如果子层设定了新的值，那么会抛弃父层的值，只使用子层的值。

• :PROPERTIES: 里面设定 :EXPORT_HUGO_SECTION: /, 输出为 content/
• :PROPERTIES: 里面设定 :EXPORT_HUGO_SECTION: notes, 输出为 content/notes/
• :PROPERTIES: 里面如果没有设定 :EXPORT_HUGO_SECTION:，那么就使用文件设定 #+hugo_section:，如果文件也没有设定，就使用默认设置。
• subtree 子层会继承父层的 :EXPORT_HUGO_SECTION:，所以不需要每个子层都设定。

subtree 设定 EXPORT_HUGO_SECTION_FRAG

:EXPORT_HUGO_SECTION_FRAG: 这个值可以继承，子层是作为父层的子目录来工作的。最上层的使用顶层的 EXPORT_HUGO_SECTION. 对于 EXPORT_HUGO_SECTION_FRAG 来说，最后的输出为 HUGO_BASE_DIR/content/EXPORT_HUGO_SECTION/EXPORT_HUGO_SECTION_FRAG 在这里 EXPORT_HUGO_SECTION_FRAG 是多次继承后的值。

示例如下:

* Main section
:PROPERTIES:
:EXPORT_HUGO_SECTION: main
:END:
The /section path/ derived at this level is ~"main/"~.
** Sub section 1
:PROPERTIES:
:EXPORT_HUGO_SECTION_FRAG: sub1
:END:
The /section path/ derived at this level is ~"main/sub1/"~.
*** Sub section 1.1
:PROPERTIES:
:EXPORT_HUGO_SECTION_FRAG: p1
:END:
The /section path/ derived at this level is ~"main/sub1/p1/"~.
*** Sub section 1.2
:PROPERTIES:
:EXPORT_HUGO_SECTION_FRAG: p2
:END:
The /section path/ derived at this level is ~"main/sub1/p2/"~.
** Sub section 2
:PROPERTIES:
:EXPORT_HUGO_SECTION_FRAG: sub2
:END:
The /section path/ derived at this level is ~"main/sub2/"~.

参考:

Hugo Section
https://ox-hugo.scripter.co/doc/hugo-section/

导出为 md

多对一，一对一 两种都能用

C-c C-e H H 即 org-hugo-export-wim-to-md，把本 subtree 的内容导出到 EXPORT_FILE_NAME 命名的 md 中去，如果全文整体导出到一个 md，那么需要 #+title
C-c C-e H A 即 org-hugo-export-wim-to-md :all-subtrees，把所有 subtree 全部导出到 EXPORT_FILE_NAME 命名的 md 中去，如果全文整体导出到一个 md，那么需要 #+title

一对一 能用

C-c C-e H h 即 org-hugo-export-to-md.

参考:

Usage
https://ox-hugo.scripter.co/doc/usage/

自动导出

保存文件时，自动导出功能，是 org-hugo-auto-export-mode，可以通过两种方式来开启。建议使用文件来开启。

整个工程开启

在 hugo 的目录下新建 .dir-locals.el 文件，并且在其中输入:

(("content-org/"
  . ((org-mode . ((eval . (org-hugo-auto-export-mode)))))))

单个文件开启

在文件末尾增加如下内容，并且增加内容后，关闭并重新打开文件，或者 M-x revert-buffer 重新加载文件，开启自动导出功能

* Footnotes
* COMMENT Local Variables                          :ARCHIVE:
# Local Variables:
# eval: (org-hugo-auto-export-mode)
# End:

全工程开启，某个文件禁用

在文件末尾增加如下内容，并且增加内容后，关闭并重新打开文件，或者 M-x revert-buffer 重新加载文件

​* Footnotes
​* COMMENT Local Variables                          :ARCHIVE:
# Local Variables:
# eval: (org-hugo-auto-export-mode -1)
# End:

参考:

Auto-export on Saving
https://ox-hugo.scripter.co/doc/auto-export-on-saving/

org 元信息

设置为使用 yaml 格式的配置文件

如果 hugo 设置的配置文件格式是 yaml，那么需要在 org 开头增加 #+hugo_front_matter_format: yaml

常用对应

toml	org	desc
title = "foo"	* foo	Subtree heading
date = 2017-09-11T14:32:00-04:00	CLOSED: [2017-09-11 Mon 14:32]	Auto-inserted CLOSED subtree property when switch to Org DONE state
publishDate = 2018-01-26	SCHEDULED: <2018-01-26 Fri>	Auto-inserted SCHEDULED subtree property using default C-c C-s binding
expiryDate = 2999-01-01	:EXPORT_HUGO_EXPIRYDATE: 2999-01-01:	Subtree property
lastmod =	:EXPORT_HUGO_AUTO_SET_LASTMOD: t	Subtree property
lastmod =	#+hugo_auto_set_lastmod: t	Org keyword
tags = ["toto", "zulu"]	* foo :toto:zulu:	Subtree heading tags
categories = ["x", "y"]	* foo :@x:@y:	Subtree heading tags with @ prefix
draft = true	* TODO foo	Subtree heading Org TODO state set to TODO1.
draft = false	* foo or * DONE foo	Subtree heading Org TODO state not set or set to DONE1.

• DONE 需要的时间戳可以 (setq org-log-done 'time)，也可以 #+STARTUP: logdone.
• :EXPORT_HUGO_AUTO_SET_LASTMOD: t 启用后，生成的 md 中的修改时间会在保存的时候自动生成。

参考:

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

格式

Org	Markdown
bold	bold
/italics/	italics
=monospace=	monospace
key-binding	key-binding
	- if org-hugo-use-code-for-kbd is nil [default]
key-binding	key-binding
	- if org-hugo-use-code-for-kbd is non-nil
	- Requires CSS to render the tag as something special.
+strike-through+	strike-through
underline	underline
	- Requires CSS to render this underline class as an underline.

参考:

Formatting
https://ox-hugo.scripter.co/doc/formatting/

时间

org-hugo-suppress-lastmod-period

如果修改的时间减去 DONE 的时间在 org-hugo-suppress-lastmod-period 设定的时间周期内，就不会添加 lastmod.

lastmod 工作机制

• subtree 中使用 :EXPORT_HUGO_AUTO_SET_LASTMOD: t 来生成。
• 全文都可用 使用 #+hugo_auto_set_lastmod: t 来生成。建议使用这种形式
• 每次保存的时候，只会自动更新鼠标所在的 subtree 对应的 lastmod.

参考:

Dates
https://ox-hugo.scripter.co/doc/dates/

图片链接

默认图片文件夹

图片默认都是放在 static/images 下面的。

• 普通图片，[[/images/org-mode-unicorn-logo-200px.png]]
• 可点击放大的缩略图，[[/images/org-mode-unicorn-logo-200px.png][file:/images/org-mode-unicorn-logo-50px.png]]
• 默认不显示图片只显示文字链接，点击才能显示图片。 [[/images/org-mode-unicorn-logo-200px.png][Click here to see org-mode-unicorn-logo-200px.png]]

外部文件夹

外部文件夹里面的图片，都会被自动复制一份到 static 文件夹下面，所以不建议这样使用。

网络图片

只要把上面的图片地址换成网络图片地址即可。

参考:

Image Links
https://ox-hugo.scripter.co/doc/image-links/

代码块

使用 <s 然后 tab 来生成一个新的代码块，然后输入代码语言比如 c, emacs-lisp 等等，然后 C-c ' 启动另外一个窗口来输入代码。

显示行号

• 在 emacs-lisp 后面追加 -n，默认从 1开始显示行数，如果追加 -n 20，表示从第 20行开始计数
• 在 emacs-lisp 后面追加 +n，默认从上一个代码块的最后一行开始顺序计数，如果追加 +n 10，表示从上一个代码块的最后一行加上 10 然后再顺序计数。

高亮某行

在 emacs-lisp 后面追加 :hl_lines 1,3-5 这样的，表示高亮第1，3-5 行。 注意虽然显示行号和高亮某行可以一起写，如: #+begin_src emacs-lisp -n 7 :hl_lines 1,3-5，但是 hugo 本身的一些问题，会导致两者一起使用时，行号显示不完全。

跳转到某处代码

在某行代码后面，增加 (ref:name) 这样的内容，就可以在这个地方设定一个 name 的锚点，然后在需要的地方使用 [[(name)]] 这样的形式就可以跳转到锚点了。 示例如下:

#+begin_src emacs-lisp
(save-excursion                 (ref:sc)
   (goto-char (point-min))      (ref:jump)
#+end_src

In line [[(sc)]] we remember the current position. [[(jump)][Line (jump)]] jumps to
~point-min~.

shortcode

ox-hugo 不推荐使用 shortcode .

参考:

Source blocks
https://ox-hugo.scripter.co/doc/source-blocks/

公式

一行公式

• 建议使用 \( \) ,不建议使用 $，因为前者可以含空格，后者不可以含空格。 \( a=b \) $a=b$
• 单独一行的结果，可以使用 \[ \] 或者 $$

LaTeX

正常时这样写:

\begin{equation}
\label{eq:1}
C = W\log_{2} (1+\mathrm{SNR})
\end{equation}

可以把 \label{SOMELABEL} 换成 \ref{SOMELABEL} ，这样就可以跳转了。

生成图片

可以把公式变为图片，但是这样就不能跳转了。 不建议。

参考:

Equations
https://ox-hugo.scripter.co/doc/equations/

标签和分类

标签

• EXPORT_HUGO_TAGS，#+filetags，subtree 不含@ 的 tag 都可以导出为标签。
• 如果某些 subtree 不希望被导出，可以在 org-export-exclude-tags 这个变量设定一个特殊的 tag，然后不希望导出的都设置为这个 tag 就可以了。

分类

• EXPORT_HUGO_CATEGORIES , #+filetags，subtree 含@ 的 tag 都可以导出为分类。
• 如果继承不正常工作，检查 org-use-tag-inheritance 是否为 t

下划线

默认 org-hugo-prefer-hyphen-in-tags 为 not nil，那么单个下划线会变成连字符，双下划线会变成空格。abc_def 转换为 abc-def, abc__def 转换为 abc def.

参考:

Tags and Categories
https://ox-hugo.scripter.co/doc/tags-and-categories/

目录

目录可以使用 hugo 自动生成的目录，也可以使用 org-mode 生成的目录。 org-mode 生成的目录可控性更强，能够更加的定制化。但是正常只需要 hugo 自动生成的就够了。

参考:

Table of Contents
https://ox-hugo.scripter.co/doc/org-toc/

表格

可以特别设定表格的属性，正常不需要用到。

参考:

Table Styling
https://ox-hugo.scripter.co/doc/table-styling/

Details and summary

测试了一下，并没有起效，后面再检查问题的原因。

参考

Details and summary
https://ox-hugo.scripter.co/doc/details-and-summary/

作者

• 可以使用 #+author: 对整个文档进行定义，如果有多个作者，那么每个作者都需要一个 #+author: 来逐行说明
• 可以使用 :EXPORT_AUTHOR: 在 subtree 的属性里面说明，多个作者使用 逗号分隔。

参考:

Author
https://ox-hugo.scripter.co/doc/author/

简介和内容分隔

#+hugo: more 可以这样进行分隔。 但是我测试也没有成功。。。

参考:

Hugo Summary Splitter
https://ox-hugo.scripter.co/doc/hugo-summary-splitter/

元信息替换

summary

ox-hugo 可以使用 #+hugo_front_matter_key_replace: description>summary ，在 org-mode 中的 description 导出时，就成为 summary。使用如下：

#+begin_description
Here is my *post summary*.

And this can be over /multiple lines/ too!
#+end_description

某些 theme 使用 keyword 不使用 tag

#+hugo_front_matter_key_replace: tags>keywords 就可以输出的时候， tags 替换成 keyword

交换 标签和分类

#+hugo_front_matter_key_replace: tags>categories categories>tags

导出时去除某属性

#+hugo_front_matter_key_replace: aliases>nil 只要替换为 nil，就不会导出这个属性。

替换作者

#+hugo_front_matter_key_replace: author>authors

参考:

Replace Front-matter Keys
https://ox-hugo.scripter.co/doc/replace-front-matter-keys/

自定义元信息

使用 #+hugo_custom_front_matter: 或者 :EXPORT_HUGO_CUSTOM_FRONT_MATTER: 来定义。

多条信息

:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :key1 value1 :key2 value2

:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :key1 value1
:EXPORT_HUGO_CUSTOM_FRONT_MATTER+: :key2 value2

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

以上三种都可以。

列表信息

:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :key1 '(elem11 elem12) :key2 '(elem21 elem22)

:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :animals '(dog cat "penguin" "mountain gorilla")
: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)

嵌套信息

:EXPORT_HUGO_CUSTOM_FRONT_MATTER: :key1 '((subkey11 . subval11) (subkey12 . (subelem121 subelem122))) :key2 '((subkey21 . subval21))

: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)))

上面这个结果是:

[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]

直接输出 toml

确保 :front_matter_extra t，toml 默认支持，所以不需要 :EXPORT_HUGO_FRONT_MATTER_FORMAT: toml

* Post with TOML front-matter (default)
:PROPERTIES:
:EXPORT_FILE_NAME: extra-front-matter-toml
:END:
The contents of the ~#+begin_src toml :front_matter_extra t~ TOML
block here will get appended to the TOML front-matter.
#+begin_src toml :front_matter_extra t
[[foo]]
  bar = 1
  zoo = "abc"
[[foo]]
  bar = 2
  zoo = "def"
#+end_src

直接输出 yaml

确保 :front_matter_extra t

* 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

参考:

Custom Front-matter Parameters
https://ox-hugo.scripter.co/doc/custom-front-matter/

svg 图片

确保 #+attr_html: :inlined t

#+begin_src plantuml :file ../test/site/content-org/images/svg-with-hyperlinks.svg :exports results
skinparam svgLinkTarget _parent
start
:[[https://ox-hugo.scripter.co/ ox-hugo homepage]];
stop
#+end_src
#+caption: An SVG with a *hyperlink*
#+attr_html: :inlined t
#+RESULTS:
[[file:../test/site/content-org/images/svg-with-hyperlinks.svg]]

参考:

Inlined SVGs
https://ox-hugo.scripter.co/doc/inlined-svgs/

CJK 多字符语言支持

• 检查 LANGUAGE, LC_ALL or LANG 看看是否是 中日韩。
• #+hugo_locale:， EXPORT_HUGO_LOCALE 可以手动设置为 zh，ja

参考:

CJK Support
https://ox-hugo.scripter.co/doc/cjk-support/

bundle

通过 :EXPORT_HUGO_BUNDLE: 来设置。 比如：:EXPORT_HUGO_BUNDLE: xyz 会生成 https://example.com/xyz/

• 含 _index.md 的是枝干，:EXPORT_FILE_NAME: _index
• 含 index.md 的是叶, :EXPORT_FILE_NAME: index

下面代码生成 content/xyz/index.md

* Page title
:PROPERTIES:
:EXPORT_HUGO_BUNDLE: xyz
:EXPORT_FILE_NAME: index
:END:
Content

下面代码生成 content/uvw/_index.md

* Page title
:PROPERTIES:
:EXPORT_HUGO_BUNDLE: uvw
:EXPORT_FILE_NAME: _index
:END:
Content

参考:

Hugo Bundle
https://ox-hugo.scripter.co/doc/hugo-bundle/

特殊区域

#+begin_.. #+end_.. 围起来的区域既是特殊区域，可以使用 html5 来渲染。

行

org-blackfriday-html5-inline-elements 这个变量中定义的可以进行行渲染

• INLINETAG 标记，使用 #+begin_INLINETAG #+end_INLINETAG
• mark 标记，使用 #+begin_mark #+end_mark

块

org-html-html5-elements 这个变量中定义的可以进行区域渲染

• BLOCKTAG 标记，使用 #+begin_BLOCKTAG #+end_BLOCKTAG
• aside 标记，使用 #+begin_aside #+end_aside

details

details 经常会和 summary 一起用

#+begin_details
#+begin_summary
This is summary.
#+end_summary
Here are the details.
#+end_details

HTML 属性

HTML 属性放在其他特殊块之前，就可以定制相关属性了。

#+begin_export html
<style>
  .red {
    color: red;
  }
</style>
#+end_export
#+attr_html: :class red
#+begin_mark
This marked text's foreground is red.
#+end_mark

生成描述

#+begin_description #+end_description 框起来的会生成到 toml 中的 description 中去。

其他 div 标记

所有不在 org-blackfriday-html5-inline-elements org-html-html5-elements 中的，都会输出为 div 标记

#+begin_SOMETHING
Content inside something.
#+end_SOMETHING

导出为

<div class="SOMETHING">

Content inside something.

</div>

比如:

#+begin_red
This text will be in red.
#+end_red

会输出为红色的这行字。

特殊区域原样输出

有时候特殊区域中的字符需要按照原样进行输出，比如希望输出的是 latex 的原始字符。那么需要在 org-hugo-special-block-type-properties 定义 类似 ("katex" . (:raw t)) 这样的。
如下:

#+begin_katex
E = -J \sum\_{i=1}^N s\_i s\_{i+1}
#+end_katex

#+begin_mermaid
flowchart TD
    Start --> Stop
#+end_mermaid

具体的设置方法是:

(with-eval-after-load 'ox-hugo
  (add-to-list 'org-hugo-special-block-type-properties '("mermaid" . (:raw t))))

TikZJax 生成图形

需要在 hugo 的网站设置中添加 head

<link rel="stylesheet" type="text/css" href="https://tikzjax.com/v1/fonts.css">
<script src="https://tikzjax.com/v1/tikzjax.js"></script>

在 org 中就可以生成了。

#+begin_tikzjax
\draw (0,0) circle (1in);
#+end_tikzjax

前后空白字符

org-hugo-special-block-type-properties 中如果设置了 :trim-pre :trim-post 为 t，那么对应的空白字符就会被去掉，默认是 nil.
设置 sidenote:

(with-eval-after-load 'ox-hugo
  (add-to-list 'org-hugo-special-block-type-properties '("sidenote" . (:trim-pre t :trim-post t))))

设置 mark:

(with-eval-after-load 'ox-hugo
  (setcdr (assoc "mark" org-hugo-special-block-type-properties) '(:trim-pre t :trim-post nil)))

也可以通过在文件中设置 #+header: 来覆盖掉设置。

设置 mark 不去除 空白字符

line 1
#+header: :trim-pre nil :trim-post nil
#+begin_mark
abc def
#+end_mark
line 2

结果如下:

line 1

abc def

line 2

参考:

Org Special Blocks
https://ox-hugo.scripter.co/doc/org-special-blocks/

Shortcodes

• 原生的 hugo Shortcodes 不支持
• {{< .. >}} {{% .. %}} 这两种格式 org 不支持

Org Special Blocks

添加 css 代码

.alert {
  position: relative;
  padding: 0rem 1rem;
  margin-bottom: 1rem;
  border: 1px solid transparent;
}

.alert-warning {
  border-style: solid;
  border-color: #ed6a5a;
  border-width: 0 0 0 4px;
}

.alert-heading {
  font-family: sans-serif;
  font-size: 1.5rem;
  color: #ed6a5a;
  weight: bold;
}

然后在文件中这样使用：

#+attr_html: :class alert-warning
#+begin_alert
#+begin_alert-heading
Warning
#+end_alert-heading
This is a warning.
#+end_alert

HUGO_PAIRED_SHORTCODES

markdown 不支持的 ({{< .. >}})

使用 :EXPORT_HUGO_PAIRED_SHORTCODES: myshortcode 或者 #+hugo_paired_shortcodes: myshortcode ，然后如下使用:

#+begin_myshortcode
Something
#+end_myshortcode

带参数

使用 #+attr_shortcode

#+attr_shortcode: argval1 "arg val 2"
#+begin_myshortcode
Something
#+end_myshortcode

有名参数

使用 #+attr_shortcode

#+attr_shortcode: :arg1 foo bar :arg2 color: red; text-align: center;
#+begin_myshortcode
Something
#+end_myshortcode

markdown 支持的 ({{% .. %}})

需要在前面加一个 %，比如 :EXPORT_HUGO_PAIRED_SHORTCODES: %myshortcode 或者 #+hugo_paired_shortcodes: %myshortcode

alert2

alert2 的定义在 layouts/shortcodes/alert2.html 。先设置 :EXPORT_HUGO_PAIRED_SHORTCODES: alert2 ，然后:

#+attr_shortcode: warning
#+begin_alert2
This is a warning.
#+end_alert2

hugo 原生的 org 不支持

@@hugo:..@@

可以这样用 This links to the @@hugo:[Org Special Blocks]({​{< relref "org-special-blocks" >}})@@ page.，或者使用 @@md:..@@ @@html:..@@

#+hugo: Keyword

可以这样用 #+hugo: This links to the [Org Special Blocks]({​{< relref "org-special-blocks" >}}) page. 或者 #+md:.. #+html:..

#+begin_export hugo

#+begin_export hugo 非常不建议使用，

#+begin_export hugo
{{< alert2 warning >}}
This is a warning.
{{< /alert2 >}}
#+end_export

也可以分行写:

#+begin_export hugo
{{< album
    position="horizontal"
    path="static/img/some/very/long/path"
>}}
#+end_export

org 宏

#+macro: relref @@hugo:[@@ $1 @@hugo:]({{< relref "$2" >}})@@ 这样定义宏以后，This links to the {{{relref(Org Special Blocks,org-special-blocks)}}} page. 可以这样使用宏。

参考:

Shortcodes
https://ox-hugo.scripter.co/doc/shortcodes/

HTML Containers

EXPORT_HTML_CONTAINER: section 可以用来生成 <section> </section>, EXPORT_HTML_CONTAINER_CLASS: 也一样

参考:

HTML Containers
https://ox-hugo.scripter.co/doc/html-containers/

锚点

命令	获取的值
org-hugo-get-page-or-bundle-name	:EXPORT_FILE_NAME
org-hugo-get-custom-id	:CUSTOM_ID
org-hugo-get-heading-slug	标题
org-hugo-get-md5	标题的 md5

org-hugo-get-id

** Heading in a post
:PROPERTIES:
:ID:       74283e7c-a20b-1c22-af88-e41ff8055d17
:END:

会导出 ### Heading in a post {#74283e7c-a20b-1c22-af88-e41ff8055d17}

参考:

Anchors
https://ox-hugo.scripter.co/doc/anchors/

链接代码，表，图像

使用 #+name 来创建跳转点，#+caption 是可选的。

代码

#+name: code__hello
#+caption: Saying "Hello" in ~emacs-lisp~
#+begin_src emacs-lisp
(message "Hello")
#+end_src

Link to the above code block: [[code__hello]]

表格

#+name: tab__simple_table
#+caption: Simple Table
|----------+----------+----------|
| Header 1 | Header 2 | Header 3 |
|----------+----------+----------|
| abc      | def      | ghi      |
|----------+----------+----------|

Link to the above table: [[tab__simple_table]]

图

#+name: fig__some_figure
#+caption: Some Figure
[[./images/some_figure.png]]

Link to the above figure: [[fig__some_figure]]

参考:

Linking numbered elements
https://ox-hugo.scripter.co/doc/linking-numbered-elements/

菜单

网站菜单构成

site
    Menus
       |                     +--------------+
       +-- "Menu Name 1" --> | Menu Entry 1 +----> Page 1
       |                     +--------------+
       |                     | Menu Entry 2 +----> Page 2
       |                     +--------------+
       |                     | ..           +----> ..
       |                     +--------------+
       |
       |                     +--------------+
       +-- "Menu Name 2" --> | Menu Entry a +----> Page a
       |                     +--------------+
       |                     | Menu Entry b +----> Page b
       |                     +--------------+
       .                     | ..           +----> ..
                             +--------------+

菜单设置信息:

Menu Entry Key	Menu Entry Variable	Brief Description
[menu.NAME]	.Menu	Name of the Menu containing the current Menu Entry
url	.URL	URL that this Menu Entry points to, defaults to page’s .RelPermalink
identifier	.Identifier	Identifier is the unique string used to identify this Menu Entry
name	.Name	Name of this Menu Entry, defaults to page’s .LinkTitle
pre	.Pre	HTML string that can be used to prefix the Menu Entry .Name
post	.Post	HTML string that can be used to postfix the Menu Entry .Name
weight	.Weight	Weight for this Menu Entry, used for sorting menus in a sidebar
parent	.Parent	Name or Identifier of this Menu Entry’s Parent Menu Entry
title	.Title (this is a function)	Used to set this Menu Entry’s link’s title attribute, defaults to page’s .LinkTitle

:EXPORT_HUGO_MENU: #+hugo_menu:

可以使用 :EXPORT_HUGO_MENU: #+hugo_menu: 来设置菜单，:EXPORT_HUGO_MENU: :menu <menu name> <:key 1> <val 1> <:key 2> <val 2> .. :menu 是必须的。

:EXPORT_HUGO_MENU: or #+hugo_menu: key	Menu Entry Front-matter	Note
:menu VAL	[menu.VAL]	mandatory
:identifier VAL	identifier = VAL	Gets auto-set to the sanitized post title if not set
:weight VAL	weight = VAL	Gets auto-set based on post subtree’s location if not set
:url VAL	url = VAL	optional
:pre VAL	pre = VAL	optional
:name VAL	name = VAL	optional
:post VAL	post = VAL	optional
:parent VAL	parent = VAL	optional
:title VAL	title = VAL	optional

示例

* 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.main]
    weight = 3001
    identifier = "post-1"

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

上面的 weight identifier 是 ox-hugo 自动生成的。

更多自定义

:EXPORT_HUGO_MENU: :menu "something here" :weight 80 :parent posts :identifier foo1 导出如下:

[menu]
  [menu."something here"]
    parent = "posts"
    weight = 80
    identifier = "foo1"

覆盖设置

:EXPORT_HUGO_MENU_OVERRIDE: 用来覆盖 menu 的设置

* 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

参考:

Menu Front-matter
https://ox-hugo.scripter.co/doc/menu-front-matter/