GETTING STARTED 入門 基本原理

配置標記語言

預設處理器

Hugo 使用 Goldmark 來將 Markdown 渲染為 HTML。

hugo.
      
markup:
  defaultMarkdownHandler: goldmark

[markup]
  defaultMarkdownHandler = 'goldmark'

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

具有 .md、.mdown 或 .markdown 副檔名的檔案將被處理為 Markdown，前提是您在前置標頭中沒有使用 markup 欄位指定其他的 [內容格式]。

若要對 Markdown 檔案使用不同的渲染器，請在您的網站配置中指定 asciidocext、org、pandoc 或 rst 中的其中一個。

defaultMarkdownHandler 描述
asciidocext AsciiDoc
goldmark Goldmark
org [Emacs Org 模式]
pandoc Pandoc
rst reStructuredText

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

Goldmark

以下為 Goldmark Markdown 渲染器的預設配置：

hugo.
      
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: true
      linkify: true
      linkifyProtocol: https
      passthrough:
        delimiters:
          block: []
          inline: []
        enable: false
      strikethrough: true
      table: true
      taskList: true
      typographer:
        apostrophe: '’'
        disable: false
        ellipsis: '…'
        emDash: '—'
        enDash: '–'
        leftAngleQuote: '«'
        leftDoubleQuote: '“'
        leftSingleQuote: '‘'
        rightAngleQuote: '»'
        rightDoubleQuote: '”'
        rightSingleQuote: '’'
    parser:
      attribute:
        block: false
        title: true
      autoHeadingID: true
      autoHeadingIDType: github
      wrapStandAloneImageWithinParagraph: true
    renderHooks:
      image:
        enableDefault: false
      link:
        enableDefault: false
    renderer:
      hardWraps: false
      unsafe: false
      xhtml: false

[markup]
  [markup.goldmark]
    duplicateResourceFiles = false
    [markup.goldmark.extensions]
      definitionList = true
      footnote = 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.passthrough]
        enable = false
        [markup.goldmark.extensions.passthrough.delimiters]
          block = []
          inline = []
      [markup.goldmark.extensions.typographer]
        apostrophe = '’'
        disable = false
        ellipsis = '…'
        emDash = '—'
        enDash = '–'
        leftAngleQuote = '«'
        leftDoubleQuote = '“'
        leftSingleQuote = '‘'
        rightAngleQuote = '»'
        rightDoubleQuote = '”'
        rightSingleQuote = '’'
    [markup.goldmark.parser]
      autoHeadingID = true
      autoHeadingIDType = 'github'
      wrapStandAloneImageWithinParagraph = true
      [markup.goldmark.parser.attribute]
        block = false
        title = true
    [markup.goldmark.renderHooks]
      [markup.goldmark.renderHooks.image]
        enableDefault = false
      [markup.goldmark.renderHooks.link]
        enableDefault = false
    [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": true,
            "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
            },
            "autoHeadingID": true,
            "autoHeadingIDType": "github",
            "wrapStandAloneImageWithinParagraph": true
         },
         "renderHooks": {
            "image": {
               "enableDefault": false
            },
            "link": {
               "enableDefault": false
            }
         },
         "renderer": {
            "hardWraps": false,
            "unsafe": false,
            "xhtml": false
         }
      }
   }
}

Goldmark 擴展功能

下列擴展功能（不包含 Extras 和 Passthrough）預設為啟用。

擴展功能 文檔 已啟用
cjk Goldmark 擴展功能: CJK ：heavy_check_mark:
definitionList PHP Markdown Extra: 定義列表 ：heavy_check_mark:
extras Hugo Goldmark 擴展功能: Extras
footnote PHP Markdown Extra: 註腳 ：heavy_check_mark:
linkify GitHub 增強 Markdown: 自動鏈接 ：heavy_check_mark:
passthrough Hugo Goldmark 擴展功能: Passthrough
strikethrough GitHub 增強 Markdown: 刪除線 ：heavy_check_mark:
table GitHub 增強 Markdown: 表格 ：heavy_check_mark:
taskList GitHub 增強 Markdown: 任務清單項目 ：heavy_check_mark:
typographer Goldmark 擴展功能: 排版器 ：heavy_check_mark:

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>

若要在啟用 Hugo Goldmark Extras 下標擴展時避免衝突，若您想同時渲染下標和刪除線文字，必須：

  1. 禁用 Goldmark 刪除線擴展
  2. 啟用 Hugo Goldmark Extras 刪除擴展

例如：

hugo.
      
markup:
  goldmark:
    extensions:
      extras:
        delete:
          enable: true
        subscript:
          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.subscript]
          enable = true

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

Passthrough

New in v0.122.0

啟用 passthrough 擴展，使用 LaTeX 或 TeX 排版語法將數學公式和表達式包含在 Markdown 中。詳細資訊請參見 Markdown 中的數學公式。

排版器

排版器擴展會將某些字元組合替換為 HTML 實體，如下所示：

Markdown 替換為 描述
... &hellip; 水平省略號
' &rsquo; 撇號
-- &ndash; en 破折號
--- &mdash; em 破折號
« &laquo; 左角引號
“ &ldquo; 左雙引號
‘ &lsquo; 左單引號
» &raquo; 右角引號
” &rdquo; 右雙引號
’ &rsquo; 右單引號 

### Goldmark 設定解釋

上述大多數 Goldmark 設定是顯而易見的，但有些設定需要進一步解釋。

###### duplicateResourceFiles


  
    New in v0.123.0
  

(`bool`) 如果設置為 `true`，在多語言的單一主機站點中，共享頁面資源會為每種語言進行複製。詳情請參見 [多語言頁面資源]。默認值是 `false`。

[多語言頁面資源]: /content-management/page-resources/#multilingual






###### parser.wrapStandAloneImageWithinParagraph

(`bool`) 如果設置為 `true`，則沒有相鄰內容的圖片元素會被包裹在 `p` 元素中進行渲染。這是默認的 Markdown 行為。如果使用 [圖片渲染鉤子] 以 `figure` 元素渲染獨立圖片，則應設置為 `false`。默認值為 `true`。

[圖片渲染鉤子]: /render-hooks/images/

###### parser.autoHeadingIDType

(`string`) 用於自動生成標題 `id` 屬性的策略，可以選擇 `github`、`github-ascii` 或 `blackfriday`。

- `github` 生成與 GitHub 兼容的 `id` 屬性
- `github-ascii` 在去除重音符號後，去除任何非 ASCII 字符
- `blackfriday` 生成與 Blackfriday Markdown 渲染器兼容的 `id` 屬性

這也是 [anchorize](/functions/urls/anchorize) 模板函數使用的策略。默認值為 `github`。

###### parser.attribute.block

(`bool`) 如果設置為 `true`，則啟用區塊元素的 [Markdown 屬性]。默認值為 `false`。

[Markdown 屬性]: /content-management/markdown-attributes/

###### parser.attribute.title

(`bool`) 如果設置為 `true`，則啟用標題的 [Markdown 屬性]。默認值為 `true`。

###### renderHooks.image.enableDefault


  
    New in v0.123.0
  

(`bool`) 如果設置為 `true`，則啟用 Hugo 的 [嵌入式圖片渲染鉤子]。默認值為 `false`。

[嵌入式圖片渲染鉤子]: /render-hooks/images/#default






###### renderHooks.link.enableDefault


  
    New in v0.123.0
  

(`bool`) 如果設置為 `true`，則啟用 Hugo 的 [嵌入式鏈接渲染鉤子]。默認值為 `false`。

[嵌入式鏈接渲染鉤子]: /render-hooks/links/#default






###### renderer.hardWraps

(`bool`) 如果設置為 `true`，Goldmark 會將段落中的換行符替換為 `br` 元素。默認值為 `false`。

###### renderer.unsafe

(`bool`) 如果設置為 `true`，Goldmark 會渲染混合在 Markdown 中的原始 HTML。這樣的設置不安全，除非該內容是由您掌控的。默認值為 `false`。

## AsciiDoc

以下是 AsciiDoc 渲染器的默認配置：




  

      

        hugo.
      

      
       
      
       
      
       
  

  

      

        
markup:
  asciidocExt:
    attributes: {}
    backend: html5
    extensions: []
    failureLevel: fatal
    noHeaderOrFooter: true
    preserveTOC: false
    safeMode: unsafe
    sectionNumbers: false
    trace: false
    verbose: false
    workingFolderCurrent: false


      

      

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


      

      

        
{
   "markup": {
      "asciidocExt": {
         "attributes": {},
         "backend": "html5",
         "extensions": [],
         "failureLevel": "fatal",
         "noHeaderOrFooter": true,
         "preserveTOC": false,
         "safeMode": "unsafe",
         "sectionNumbers": false,
         "trace": false,
         "verbose": false,
         "workingFolderCurrent": false
      }
   }
}


      

  





### AsciiDoc 設定解釋

###### attributes

(`map`) 一個鍵值對映射，每個都是文檔屬性。請參見 Asciidoctor 的 [屬性]。

[屬性]: https://asciidoctor.org/docs/asciidoc-syntax-quick-reference/#attributes-and-substitutions

###### backend

(`string`) 輸出的後端文件格式。默認值為 `html5`。

###### extensions

(`string array`) 啟用的擴展功能的數組，可以是以下之一或多個：`asciidoctor-html5s`、`asciidoctor-bibtex`、`asciidoctor-diagram`、`asciidoctor-interdoc-reftext`、`asciidoctor-katex`、`asciidoctor-latex`、`asciidoctor-mathematical` 或 `asciidoctor-question`。






###### failureLevel

(`string`) 觸發非零退出碼（錯誤）的最小日誌級別。默認值為 `fatal`。

###### noHeaderOrFooter

(`bool`) 如果設置為 `true`，則輸出一個可嵌入的文檔，排除了標題、頁腳以及文檔體以外的部分。默認值為 `true`。

###### preserveTOC

(`bool`) 如果設置為 `true`，則保留 Asciidoctor 渲染的目錄（TOC）。默認情況下，為了與現有主題兼容，Hugo 會移除 Asciidoctor 渲染的 TOC。如果要渲染 TOC，請使用模板中的 [`TableOfContents`] 方法。默認值為 `false`。

[`TableOfContents`]: /methods/page/tableofcontents/

###### safeMode

(`string`) 安全模式級別，可以是 `unsafe`、`safe`、`server` 或 `secure`。默認值為 `unsafe`。

###### sectionNumbers

(`bool`) 如果設置為 `true`，則對每個章節標題進行編號。默認值為 `false`。

###### trace

(`bool`) 如果設置為 `true`，則包含錯誤的回溯信息。默認值為 `false`。

###### verbose

(`bool`) 如果設置為 `true`，則詳細打印處理信息和配置文件檢查到 stderr。默認值為 `false`。

###### workingFolderCurrent

(`bool`) 如果設置為 `true`，則將工作目錄設置為與正在處理的 AsciiDoc 文件相同，允許 [包含] 使用相對路徑。設置為 `true` 可與 [asciidoctor-diagram] 擴展一起渲染圖表。默認值為 `false`。

[asciidoctor-diagram]: https://asciidoctor.org/docs/asciidoctor-diagram/
[包含]: https://docs.asciidoctor.org/asciidoc/latest/syntax-quick-reference/#includes

### AsciiDoc 配置示例




  

      

        hugo.
      

      
       
      
       
      
       
  

  

      

        
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
      }
   }
}


      

  





### AsciiDoc 語法高亮

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

步驟 1：
: 在您的站點配置中設置 `source-highlighter` 屬性。例如：




  

      

        hugo.
      

      
       
      
       
      
       
  

  

      

        
markup:
  asciidocExt:
    attributes:
      source-highlighter: rouge


      

      

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


      

      

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


      

  





步驟 2：
: 生成高亮的 CSS。例如：

```text
rougify style monokai.sublime > assets/css/syntax.css
步驟 3：
在您的基礎模板中添加指向 CSS 文件的鏈接：
layouts/_default/baseof.html
<head>
  ...
  {{ with resources.Get "css/syntax.css" }}
    <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
  {{ end }}
  ...
</head>

然後將要高亮顯示的代碼添加到您的標記中：

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

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

AsciiDoc 故障排除

運行 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

這是預設的 highlight 設定。請注意，部分設定可以針對每個程式碼區塊進行設置，詳情請參見 語法高亮。

hugo.
      
markup:
  highlight:
    anchorLineNos: false
    codeFences: true
    guessSyntax: false
    hl_Lines: ""
    hl_inline: false
    lineAnchors: ""
    lineNoStart: 1
    lineNos: false
    lineNumbersInTable: true
    noClasses: true
    noHl: false
    style: monokai
    tabWidth: 4

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

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

關於 style，請參考這些資料庫：

若您需要 CSS，請參見 生成語法高亮顯示 CSS。

目錄

以下是適用於 Goldmark 和 Asciidoctor 的預設目錄設定：

hugo.
      
markup:
  tableOfContents:
    endLevel: 3
    ordered: false
    startLevel: 2

[markup]
  [markup.tableOfContents]
    endLevel = 3
    ordered = false
    startLevel = 2

{
   "markup": {
      "tableOfContents": {
         "endLevel": 3,
         "ordered": false,
         "startLevel": 2
      }
   }
}
startLevel

(int) 小於此值的標題層級將被排除在目錄之外。例如，若希望將 h1 元素排除在目錄外，可以將此值設定為 2。預設值為 2。

endLevel

(int) 大於此值的標題層級將被排除在目錄之外。例如，若希望將 h4、h5 和 h6 元素排除在目錄外，可以將此值設定為 3。預設值為 3。

ordered

(bool) 若設為 true，會生成有序列表（而非無序列表）。預設值為 false。

延伸閱讀

Front matter 標題渲染 Hook