Hugo框架中文文档 4--Hugo内容格式 Content Format

可以在 /content目录下放置任何文件类型，不过Hugo使用markup前端(如果已经设定)设定值或者通过文件扩展名(见下面表格中Markup identifiers)来决定markup是否需要处理,比如:

Markdown 转化成HTML
Shortcodes 处理转化
应用Layout布局

内容格式列表

当前Hugo支持的内容格式:

名称	标记标志	备注
Goldmark	md, markdown, goldmark	注意可以将默认的markdown处理器设置成其他处理器, 请见配置Markup
Blackfriday	blackfriday	Blackfriday 以后最终会被废弃使用.
MMark	mmark	Mmark 已经弃用，将会在近期发布版本中移除.
Emacs Org-Mode	org	参考 go-org
AsciiDoc	asciidocext, adoc, ad	需要安装 Asciidoctor
RST	rst	需要安装 RST
Pandoc	pandoc, pdc	需要安装 Pandoc
HTML	html, htm	作为内容文件处理, 解析布局、短代码。必须设置了front matter。如果没设置，会按原样copy

标志标记 markup identifier 从front matter中设置的markup变量获取, 或者从文件扩展名的到. 更多标记相关设定，请参考配置标记.

外部帮助程序

上表中一个内容格式需要您的计算机上安装的外部命令的帮助。比如, 对于AsciiDoc文件Hugo会尝试调用asciidoctor命令，这意味着您必须在您的机器上安装相关的工具才能利用这些格式

Hugo调用这些命令时会默认传递合理的缺省参数给这些命令:

asciidoctor: --no-header-footer -
rst2html: --leave-comments --initial-header-level=2
pandoc: --mathjax

由于处理额外的文件格式需要使用外部命令, 网站生成效率可能严重依赖于所使用的外部命令的效率。这个特性还很新颖，欢迎反馈信息。

外部帮助命令 AsciiDoc

在2020年一月AsciiDoc命令工具的实现结束了生命周期，不在受支持.

AsciiDoc的实现在2020年一月结束了生命周期 AsciiDoc的开发由Asciidoctor继续。格式当然还是AsciiDoc格式。请继续使用Asciidoctor的实现。

外部帮助命令 Asciidoctor

Asciidoctor社区为AsciiDoc格式提供了广泛的工具集，可以安装作为Hugo的附加工具

参考Asciidoctor文档获取安装指导. 请确保所有可选扩展比如asciidoctor-diagram 或者 asciidoctor-html5s 被安装, 如果有需要。

外部命令 asciidoctor 要求Hugo输出到_磁盘_的特定目标目录。因此要求运行Hugo时需要提供命令行参数 --destination.

有些 Asciidoctor 参数可以在Hugo内定制:

参数	评论
backend	如果不知道自己在做什么不要修改这个参数.
doctype	当前, hugo支持的唯一文档类型是 `article`.
extensions	可能的扩展包括 `asciidoctor-html5s`, `asciidoctor-bibtex`, `asciidoctor-diagram`, `asciidoctor-interdoc-reftext`, `asciidoctor-katex`, `asciidoctor-latex`, `asciidoctor-mathematical`, `asciidoctor-question`, `asciidoctor-rouge`.
attributes	可以在AsciiDoc文件中引用的变量参数。这是值名称或者名称-值对的列表。参考 Asciidoctor’s attributes.
noHeaderOrFooter	输出可嵌入的文档, 删除了除主体文档外一切，如头部、尾部。不要修改这个参数，除非您了解自己在做什么。
safeMode	安全模式级别 `unsafe`, `safe`, `server` or `secure`. 不要修改这个参数，除非您了解自己在做什么。
sectionNumbers	自动区块头部进行序数标记 Auto-number section titles.
verbose	冗余打印处理信息和配置文件检查信息到标准错误输出stderr.
trace	出错时包含回溯信息.
failureLevel	引发非零退出码失败的最小日志级别.

Hugo还提供了不直接与Asciidoctor的命令行选项对应的额外的设置选项:

workingFolderCurrent: 设置Hugo的工作目录为和ASciiDoc处理的文件目录一致，由此include会在相对目录下工作。这个设置使用了 asciidoctor命令行参数--base-dir 和属性 outdir=。对于使用asciidoctor-diagram输出图片,workingFolderCurrent必须设置为true.

preserveTOC :默认情况下，Hugo会删除Asciidoctor生成的文章目录,并且通过内置变量.TableOfContents来提供目录, 以便后期更多配置以及与多个Hugo主题的更好集成。这个选项可以设置成true来保留Asciidoctor生成的TOC目录在生成的页面中.

下表是Hugo内和AsciiDoc相关的所有设定以及它们的默认值:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
markup:
  asciidocExt:
    attributes: {}
    backend: html5
    extensions: []
    failureLevel: fatal
    noHeaderOrFooter: true
    preserveTOC: false
    safeMode: unsafe
    sectionNumbers: false
    trace: false
    verbose: false
    workingFolderCurrent: false

设定扩展和属性的例子:

1
2
3
4
5
6
[markup.asciidocExt]
    extensions = ["asciidoctor-html5s", "asciidoctor-diagram"]
    workingFolderCurrent = true
    [markup.asciidocExt.attributes]
        my-base-url = "https://example.com/"
        my-attribute-name = "my value"

在复杂的Asciidoctor环境中，有时调试输出外部命令的真实的所有参数会有些帮助。使用参数-v调用Hugo,您会得到类似下面输出:

1
INFO 2019/12/22 09:08:48 Rendering book-as-pdf.adoc with C:\Ruby26-x64\bin\asciidoctor.bat using asciidoc args [--no-header-footer -r asciidoctor-html5s -b html5s -r asciidoctor-diagram --base-dir D:\prototypes\hugo_asciidoc_ddd\docs -a outdir=D:\prototypes\hugo_asciidoc_ddd\build -] ...

学习 Markdown

学习markdown很简单，学习一会儿就够了。下面的开始学习markdown的优秀资源: