Hugo框架中文文档 Hugo内容格式

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

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

内容格式列表

当前Hugo支持的内容格式:

标志标记 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内定制:

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
 7
 8
 9
10
11
12
13
14

[markup]
  [markup.asciidocExt]
    backend = 'html5'
    extensions = []
    failureLevel = 'fatal'
    noHeaderOrFooter = true
    preserveTOC = false
    safeMode = 'unsafe'
    sectionNumbers = false
    trace = false
    verbose = false
    workingFolderCurrent = false

    [markup.asciidocExt.attributes]

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

{
   "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的优秀资源:

• Daring Fireball: Markdown, John Gruber (Markdown的创建者)
• Markdown Cheatsheet, Adam Pritchard
• Markdown Tutorial (Interactive), Garen Torikian
• The Markdown Guide, Matt Cone