Hugo 配置標記

Hugo 配置標記。

默認處理器

在默認配置中，Hugo 使用 Goldmark 將 Markdown 渲染為 HTML。

markup:
  defaultMarkdownHandler: goldmark

[markup]
  defaultMarkdownHandler = 'goldmark'

{
   "markup": {
      "defaultMarkdownHandler": "goldmark"
   }
}

以 .md、.mdown 或 .markdown 結尾的文件作為 Markdown 處理，除非您在 front matter 中使用 markup 字段顯式設置了不同的格式。

要為 Markdown 文件使用不同的渲染器，在站點配置中指定 asciidocext、org、pandoc 或 rst 之一。

`defaultMarkdownHandler`	渲染器
`asciidocext`	AsciiDoc
`goldmark`	Goldmark
`org`	Emacs Org Mode
`pandoc`	Pandoc
`rst`	reStructuredText

要使用 AsciiDoc、Pandoc 或 reStructuredText，您必須安裝相關的渲染器並更新安全策略。

除非您需要替代 Markdown 處理器提供的獨特功能，否則我們強烈建議您使用默認設置。Goldmark 速度快、維護良好、符合 CommonMark 規范，並與 GitHub Flavored Markdown (GFM) 兼容。

Goldmark

這是 Goldmark Markdown 渲染器的默認配置：

markup:
  goldmark:
    duplicateResourceFiles: false
    extensions:
      cjk:
        eastAsianLineBreaks: false
        eastAsianLineBreaksStyle: simple
        enable: false
        escapedSpace: false
      definitionList: true
      extras:
        delete:
          enable: false
        insert:
          enable: false
        mark:
          enable: false
        subscript:
          enable: false
        superscript:
          enable: false
      footnote:
        backlinkHTML: '&#x21a9;&#xfe0e;'
        enable: true
        enableAutoIDPrefix: false
      linkify: true
      linkifyProtocol: https
      passthrough:
        delimiters:
          block: &block
[]
          inline: &block *block
        enable: false
      strikethrough: true
      table: true
      taskList: true
      typographer:
        apostrophe: '&rsquo;'
        disable: false
        ellipsis: '&hellip;'
        emDash: '&mdash;'
        enDash: '&ndash;'
        leftAngleQuote: '&laquo;'
        leftDoubleQuote: '&ldquo;'
        leftSingleQuote: '&lsquo;'
        rightAngleQuote: '&raquo;'
        rightDoubleQuote: '&rdquo;'
        rightSingleQuote: '&rsquo;'
    parser:
      attribute:
        block: false
        title: true
      autoDefinitionTermID: false
      autoHeadingID: true
      autoIDType: github
      wrapStandAloneImageWithinParagraph: true
    renderHooks:
      image:
        enableDefault: false
        useEmbedded: auto
      link:
        enableDefault: false
        useEmbedded: auto
    renderer:
      hardWraps: false
      unsafe: false
      xhtml: false

[markup]
  [markup.goldmark]
    duplicateResourceFiles = false
    [markup.goldmark.extensions]
      definitionList = true
      linkify = true
      linkifyProtocol = 'https'
      strikethrough = true
      table = true
      taskList = true
      [markup.goldmark.extensions.cjk]
        eastAsianLineBreaks = false
        eastAsianLineBreaksStyle = 'simple'
        enable = false
        escapedSpace = false
      [markup.goldmark.extensions.extras]
        [markup.goldmark.extensions.extras.delete]
          enable = false
        [markup.goldmark.extensions.extras.insert]
          enable = false
        [markup.goldmark.extensions.extras.mark]
          enable = false
        [markup.goldmark.extensions.extras.subscript]
          enable = false
        [markup.goldmark.extensions.extras.superscript]
          enable = false
      [markup.goldmark.extensions.footnote]
        backlinkHTML = '&#x21a9;&#xfe0e;'
        enable = true
        enableAutoIDPrefix = false
      [markup.goldmark.extensions.passthrough]
        enable = false
        [markup.goldmark.extensions.passthrough.delimiters]
          block = []
          inline = []
      [markup.goldmark.extensions.typographer]
        apostrophe = '&rsquo;'
        disable = false
        ellipsis = '&hellip;'
        emDash = '&mdash;'
        enDash = '&ndash;'
        leftAngleQuote = '&laquo;'
        leftDoubleQuote = '&ldquo;'
        leftSingleQuote = '&lsquo;'
        rightAngleQuote = '&raquo;'
        rightDoubleQuote = '&rdquo;'
        rightSingleQuote = '&rsquo;'
    [markup.goldmark.parser]
      autoDefinitionTermID = false
      autoHeadingID = true
      autoIDType = 'github'
      wrapStandAloneImageWithinParagraph = true
      [markup.goldmark.parser.attribute]
        block = false
        title = true
    [markup.goldmark.renderHooks]
      [markup.goldmark.renderHooks.image]
        enableDefault = false
        useEmbedded = 'auto'
      [markup.goldmark.renderHooks.link]
        enableDefault = false
        useEmbedded = 'auto'
    [markup.goldmark.renderer]
      hardWraps = false
      unsafe = false
      xhtml = false

{
   "markup": {
      "goldmark": {
         "duplicateResourceFiles": false,
         "extensions": {
            "cjk": {
               "eastAsianLineBreaks": false,
               "eastAsianLineBreaksStyle": "simple",
               "enable": false,
               "escapedSpace": false
            },
            "definitionList": true,
            "extras": {
               "delete": {
                  "enable": false
               },
               "insert": {
                  "enable": false
               },
               "mark": {
                  "enable": false
               },
               "subscript": {
                  "enable": false
               },
               "superscript": {
                  "enable": false
               }
            },
            "footnote": {
               "backlinkHTML": "\u0026#x21a9;\u0026#xfe0e;",
               "enable": true,
               "enableAutoIDPrefix": false
            },
            "linkify": true,
            "linkifyProtocol": "https",
            "passthrough": {
               "delimiters": {
                  "block": [],
                  "inline": []
               },
               "enable": false
            },
            "strikethrough": true,
            "table": true,
            "taskList": true,
            "typographer": {
               "apostrophe": "\u0026rsquo;",
               "disable": false,
               "ellipsis": "\u0026hellip;",
               "emDash": "\u0026mdash;",
               "enDash": "\u0026ndash;",
               "leftAngleQuote": "\u0026laquo;",
               "leftDoubleQuote": "\u0026ldquo;",
               "leftSingleQuote": "\u0026lsquo;",
               "rightAngleQuote": "\u0026raquo;",
               "rightDoubleQuote": "\u0026rdquo;",
               "rightSingleQuote": "\u0026rsquo;"
            }
         },
         "parser": {
            "attribute": {
               "block": false,
               "title": true
            },
            "autoDefinitionTermID": false,
            "autoHeadingID": true,
            "autoIDType": "github",
            "wrapStandAloneImageWithinParagraph": true
         },
         "renderHooks": {
            "image": {
               "enableDefault": false,
               "useEmbedded": "auto"
            },
            "link": {
               "enableDefault": false,
               "useEmbedded": "auto"
            }
         },
         "renderer": {
            "hardWraps": false,
            "unsafe": false,
            "xhtml": false
         }
      }
   }
}

擴展

下面的擴展中，除了 Extras 和 Passthrough 外，默認都啟用。

擴展	文檔	啟用
`cjk`	Goldmark Extensions: CJK	✔️
`definitionList`	PHP Markdown Extra: Definition lists	✔️
`extras`	Hugo Goldmark Extensions: Extras
`footnote`	PHP Markdown Extra: Footnotes	✔️
`linkify`	GitHub Flavored Markdown: Autolinks	✔️
`passthrough`	Hugo Goldmark Extensions: Passthrough
`strikethrough`	GitHub Flavored Markdown: Strikethrough	✔️
`table`	GitHub Flavored Markdown: Tables	✔️
`taskList`	GitHub Flavored Markdown: Task list items	✔️
`typographer`	Goldmark Extensions: Typographer	✔️

Extras

New in v0.126.0

在 Markdown 中啟用刪除文本、插入文本、標記文本、下標和上標元素。

元素	Markdown	渲染
刪除文本	`~~foo~~`	`<del>foo</del>`
插入文本	`++bar++`	`<ins>bar</ins>`
標記文本	`==baz==`	`<mark>baz</mark>`
下標	`H~2~O`	`H<sub>2</sub>O`
上標	`1^st^`	`1<sup>st</sup>`

為避免沖突¹，如果您啟用 Extras 擴展的"下標"功能，則必須禁用 Strikethrough 擴展：

markup:
  goldmark:
    extensions:
      extras:
        subscript:
          enable: true
      strikethrough: false

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      strikethrough = false
      [markup.goldmark.extensions.extras]
        [markup.goldmark.extensions.extras.subscript]
          enable = true

{
   "markup": {
      "goldmark": {
         "extensions": {
            "extras": {
               "subscript": {
                  "enable": true
               }
            },
            "strikethrough": false
         }
      }
   }
}

如果在禁用 Strikethrough 擴展後仍需要顯示刪除文本，請啟用 Extras 擴展的"刪除文本"功能：

markup:
  goldmark:
    extensions:
      extras:
        delete:
          enable: true
      strikethrough: false

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      strikethrough = false
      [markup.goldmark.extensions.extras]
        [markup.goldmark.extensions.extras.delete]
          enable = true

{
   "markup": {
      "goldmark": {
         "extensions": {
            "extras": {
               "delete": {
                  "enable": true
               }
            },
            "strikethrough": false
         }
      }
   }
}

使用此配置，要格式化刪除文本，請使用雙波浪號包裹。

Footnote

默認啟用，Footnote 擴展允許在 Markdown 中包含腳注。

enable: New in v0.151.0; (bool) 是否啟用 Footnotes 擴展。默認值是 true。
backlinkHTML: New in v0.151.0; (string) 在腳注末尾顯示的 HTML，將用戶鏈接回正文中相應的引用。默認值是 ↩︎（返回箭頭符號）。
enableAutoIDPrefix: New in v0.151.0; (bool) 是否在腳注 ID 前添加唯一前綴，防止多個文檔一起渲染時發生沖突。此前綴對每個邏輯路徑是唯一的，這意味著前綴在不同內容維度（如語言）之間不是唯一的。默認值是 false。

Passthrough

啟用 Passthrough 擴展以在 Markdown 中使用 LaTeX 標記包含數學方程和表達式。詳見 Markdown 中的數學。

Typographer

Typographer 擴展將某些字符組合替換為如下指定的 HTML 實體：

Markdown	替換為	描述
`...`	`…`	水平省略號
`'`	`’`	撇號
`--`	`–`	短破折號
`---`	`—`	長破折號
`«`	`«`	左尖引號
`"`	`“`	左雙引號
`'`	`‘`	左單引號
`»`	`»`	右尖引號
`"`	`”`	右雙引號
`'`	`’`	右單引號

Goldmark 設置說明

大多數 Goldmark 設置是不言自明的，但有些需要說明。

duplicateResourceFiles

(bool) 是否在多語言單主機站點上為每種語言復制共享頁面資源。詳見多語言頁面資源。默認值是 false。

對於多語言單主機站點，將此參數設置為 false 將啟用 Hugo 的嵌入式鏈接渲染鉤子和嵌入式圖片渲染鉤子。這是多語言單主機站點的默認配置。

parser.wrapStandAloneImageWithinParagraph

(bool) 是否在渲染時將沒有相鄰內容的圖片元素包裹在 p 元素中。這是默認 Markdown 行為。當使用圖片渲染鉤子將獨立圖片渲染為 figure 元素時設置為 false。默認值是 true。

parser.autoDefinitionTermID

New in v0.144.0

(bool) 是否自動為描述列表術語（即 dt 元素）添加 id 屬性。當為 true 時，每個 dt 元素的 id 屬性可通過 Page 對象上的 Fragments.Identifiers 方法訪問。

parser.autoHeadingID

(bool) 是否自動為標題（即 h1、h2、h3、h4、h5 和 h6 元素）添加 id 屬性。

parser.autoIDType

(string) 自動生成 id 屬性的策略，github、github-ascii 或 blackfriday 之一。默認值是 github。

github: 生成與 GitHub 兼容的 id 屬性
github-ascii: 在重音標准化後刪除任何非 ASCII 字符
blackfriday: 生成與 Blackfriday Markdown 渲染器兼容的 id 屬性

這也是 anchorize 模板函數使用的策略。

parser.attribute.block

(bool) 是否為塊元素啟用 Markdown 屬性。默認值是 false。

parser.attribute.title

(bool) 是否為標題啟用 Markdown 屬性。默認值是 true。

renderHooks.image.enableDefault

在 v0.148.0 中棄用。改用 renderHooks.image.useEmbedded。

renderHooks.image.useEmbedded

New in v0.148.0

(string) 何時使用嵌入式圖片渲染鉤子。auto、never、always 或 fallback 之一。默認值是 auto。

auto: 僅對禁用了共享頁面資源復制功能的多語言單主機項目使用嵌入式圖片渲染鉤子。如果您的項目、模塊或主題定義了自定義圖片渲染鉤子，則將使用這些鉤子。
never: 從不使用嵌入式圖片渲染鉤子。如果您的項目、模塊或主題定義了自定義圖片渲染鉤子，則將使用這些鉤子。
always: 始終使用嵌入式圖片渲染鉤子，即使您的項目、模塊或主題提供了自定義圖片渲染鉤子。
fallback: 僅當您的項目、模塊或主題未提供自定義圖片渲染鉤子時使用嵌入式圖片渲染鉤子。如果存在自定義圖片渲染鉤子，則將使用這些鉤子。

renderHooks.link.enableDefault

在 v0.148.0 中棄用。改用 renderHooks.link.useEmbedded。

renderHooks.link.useEmbedded

(string) 何時使用嵌入式鏈接渲染鉤子。auto、never、always 或 fallback 之一。默認值是 auto。

auto: 僅對禁用了共享頁面資源復制功能的多語言單主機項目使用嵌入式鏈接渲染鉤子。如果您的項目、模塊或主題定義了自定義鏈接渲染鉤子，則將使用這些鉤子。
never: 從不使用嵌入式鏈接渲染鉤子。如果您的項目、模塊或主題定義了自定義鏈接渲染鉤子，則將使用這些鉤子。
always: 始終使用嵌入式鏈接渲染鉤子，即使您的項目、模塊或主題提供了自定義鏈接渲染鉤子。
fallback: 僅當您的項目、模塊或主題未提供自定義鏈接渲染鉤子時使用嵌入式鏈接渲染鉤子。如果存在自定義鏈接渲染鉤子，則將使用這些鉤子。

renderer.hardWraps

(bool) 是否將段落內的換行符替換為 br 元素。默認值是 false。

renderer.unsafe

(bool) 是否渲染 Markdown 中混合的原始 HTML。除非內容在您的控制之下，否則這是不安全的。默認值是 false。

AsciiDoc

這是 AsciiDoc 渲染器的默認配置：

markup:
  asciidocExt: null

[markup]

{
   "markup": {
      "asciidocExt": null
   }
}

AsciiDoc 設置說明

attributes: (map) 鍵值對映射，每個都是文檔屬性。詳見 Asciidoctor 的屬性。
backend: (string) 後端輸出文件格式。默認值是 html5。
extensions: ([]string) 啟用擴展的數組，如 asciidoctor-html5s、asciidoctor-bibtex 或 asciidoctor-diagram。

為了減輕安全風險，擴展數組中的條目不能包含正斜槓 (/)、反斜槓 (\) 或句點。由於此限制，擴展必須在 Ruby 的 $LOAD_PATH 中。
failureLevel: (string) 觸發非零退出代碼（失敗）的最小日志記錄級別。默認值是 fatal。
noHeaderOrFooter: (bool) 是否輸出可嵌入文檔，不包括文檔的頭部、尾部和正文之外的所有內容。默認值是 true。
preserveTOC: (bool) 是否保留 Asciidoctor 渲染的目錄 (TOC)。默認情況下，為了使 TOC 與現有主題兼容，Hugo 會移除 Asciidoctor 渲染的 TOC。要渲染 TOC，在模板中使用 Page 對象上的 TableOfContents 方法。默認值是 false。
safeMode: (string) 安全模式級別，unsafe、safe、server 或 secure 之一。默認值是 unsafe。
sectionNumbers: (bool) 是否為每個章節標題編號。默認值是 false。
trace: (bool) 是否在錯誤時包含回溯信息。默認值是 false。
verbose: (bool) 是否詳細打印處理信息和配置文件檢查到 stderr。默認值是 false。
workingFolderCurrent: (bool) 是否將工作目錄設置為與正在處理的 AsciiDoc 文件相同，允許包含使用相對路徑。設置為 true 以使用 asciidoctor-diagram 擴展渲染圖表。默認值是 false。

配置示例

markup:
  asciidocExt:
    attributes:
      my-attribute-name: my value
      my-base-url: https://example.com/
    extensions:
    - asciidoctor-html5s
    - asciidoctor-diagram
    workingFolderCurrent: true

[markup]
  [markup.asciidocExt]
    extensions = ['asciidoctor-html5s', 'asciidoctor-diagram']
    workingFolderCurrent = true
    [markup.asciidocExt.attributes]
      my-attribute-name = 'my value'
      my-base-url = 'https://example.com/'

{
   "markup": {
      "asciidocExt": {
         "attributes": {
            "my-attribute-name": "my value",
            "my-base-url": "https://example.com/"
         },
         "extensions": [
            "asciidoctor-html5s",
            "asciidoctor-diagram"
         ],
         "workingFolderCurrent": true
      }
   }
}

語法高亮

按照以下步驟啟用語法高亮。

步驟 1

在站點配置中設置 source-highlighter 屬性。例如：

markup:
  asciidocExt:
    attributes:
      source-highlighter: rouge

[markup]
  [markup.asciidocExt]
    [markup.asciidocExt.attributes]
      source-highlighter = 'rouge'

{
   "markup": {
      "asciidocExt": {
         "attributes": {
            "source-highlighter": "rouge"
         }
      }
   }
}

步驟 2

生成高亮器 CSS。例如：

rougify style monokai.sublime > assets/css/syntax.css

步驟 3

在基礎模板中添加指向 CSS 文件的鏈接：

layouts/baseof.html

<head>
  ...
  {{ with resources.Get "css/syntax.css" }}
    <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
  {{ end }}
  ...
</head>

步驟 4

在標記中添加要高亮的代碼：

[#hello,ruby]
----
require 'sinatra'

get '/hi' do
  "Hello World!"
end
----

故障排除

運行 hugo --logLevel debug 檢查 Hugo 對 Asciidoctor 可執行文件的調用：

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

Highlight

這是默認配置。

markup:
  highlight:
    anchorLineNos: false
    codeFences: true
    guessSyntax: false
    hl_Lines: ''
    hl_inline: false
    lineAnchors: ''
    lineNoStart: 1
    lineNos: false
    lineNumbersInTable: true
    noClasses: true
    style: monokai
    tabWidth: 4
    wrapperClass: highlight

[markup]
  [markup.highlight]
    anchorLineNos = false
    codeFences = true
    guessSyntax = false
    hl_Lines = ''
    hl_inline = false
    lineAnchors = ''
    lineNoStart = 1
    lineNos = false
    lineNumbersInTable = true
    noClasses = true
    style = 'monokai'
    tabWidth = 4
    wrapperClass = 'highlight'

{
   "markup": {
      "highlight": {
         "anchorLineNos": false,
         "codeFences": true,
         "guessSyntax": false,
         "hl_Lines": "",
         "hl_inline": false,
         "lineAnchors": "",
         "lineNoStart": 1,
         "lineNos": false,
         "lineNumbersInTable": true,
         "noClasses": true,
         "style": "monokai",
         "tabWidth": 4,
         "wrapperClass": "highlight"
      }
   }
}

anchorLineNos

(bool) 是否將每個行號渲染為 HTML 錨元素，將周圍 span 元素的 id 屬性設置為行號。如果 lineNos 為 false，則此選項無關。默認為 false。

codeFences

(bool) 是否高亮代碼圍欄。默認為 true。

guessSyntax

(bool) 如果 LANG 參數為空或設置為沒有相應詞法分析器的語言，是否自動檢測語言。如果無法自動檢測語言，則回退到純文本詞法分析器。默認為 false。

Chroma 語法高亮器包含約 250 種語言的詞法分析器，但其中只有 5 種實現了自動語言檢測。

hl_Lines

(string) 要在高亮代碼中強調的行的空格分隔列表。要強調第 2、3、4 和 7 行，將此值設置為 2-4 7。此選項獨立於 lineNoStart 選項。

hl_inline

(bool) 是否在沒有包裝容器的情況下渲染高亮代碼。默認為 false。

lineAnchors

(string) 在將行號渲染為 HTML 錨元素時，將此值前置到周圍 span 元素的 id 屬性。當頁面包含兩個或更多代碼塊時，這提供了唯一的 id 屬性。如果 lineNos 或 anchorLineNos 為 false，則此選項無關。

lineNoStart

(int) 在第一行顯示的數字。如果 lineNos 為 false，則此選項無關。默認為 1。

lineNos

(any) 控制行號顯示。默認為 false。

true：啟用行號，由 lineNumbersInTable 控制。
false：禁用行號。
inline：啟用內聯行號（將 lineNumbersInTable 設置為 false）。
table：啟用基於表格的行號（將 lineNumbersInTable 設置為 true）。

lineNumbersInTable

(bool) 是否在 HTML 表格中渲染高亮代碼，包含兩個單元格。左表格單元格包含行號，右表格單元格包含代碼。如果 lineNos 為 false，則此選項無關。默認為 true。

noClasses

(bool) 是否使用內聯 CSS 樣式而不是外部 CSS 文件。默認為 true。要使用外部 CSS 文件，將此值設置為 false 並從命令行生成 CSS 文件：

hugo gen chromastyles --style=monokai > syntax.css

style

(string) 應用於高亮代碼的 CSS 樣式。區分大小寫。默認為 monokai。請參閱語法高亮樣式。

tabWidth

(int) 用此數量的空格替換高亮代碼中的每個制表符。如果 noClasses 為 false，則此選項無關。默認為 4。

wrapperClass

New in v0.140.2

(string) 用於高亮代碼最外層元素的類。默認為 highlight。

startLevel: (int) 小於此值的標題級別將從目錄中排除。例如，要從目錄中排除 h1 元素，將此值設置為 2。默認值是 2。
endLevel: (int) 大於此值的標題級別將從目錄中排除。例如，要從目錄中排除 h4、h5 和 h6 元素，將此值設置為 3。默認值是 3。
ordered: (bool) 是否生成有序列表而不是無序列表。默認值是 false。

詳見詳情。 ↩︎

Last updated: January 1, 0001

Improve this page