HUGO ja 非公式

  • ニュース
  • ドキュメント
  • テーマ
  • コミュニティ
  • GitHub
gohugoio Star づけ
  暫定公開中 2024/09/16 (94d7f576a 対応, 2024/09/15)
  • Hugo について
    • 本節
    • Introduction
    • Hugo の機能
    • Privacy
    • セキュリティ
    • ライセンス
  • インストール
    • 本節
    • macOS
    • Linux
    • Windows
    • BSD
  • はじめよう
    • 本節
    • クイックスタート
    • ディレクトリ構造
    • 基本操作
    • 設定
    • Configure markup
    • 用語集
    • 本書以外の学習リソース
  • クイックリファレンス
    • 本節
    • Emojis
    • Functions
    • Methods
    • Page collections
  • コンテント管理
    • 本節
    • コンテントの構成
    • ページバンドル
    • コンテントフォーマット
    • フロントマター
    • ビルドオプション
    • ページリソース
    • イメージ処理
    • ショートコード
    • 関連コンテント
    • Sections
    • Content types
    • アーキタイプ
    • 分類
    • Summaries
    • Links and cross references
    • URL 管理
    • メニュー
    • コメント
    • マルチ言語
    • Markdown attributes
    • シンタックスハイライト
    • Diagrams
    • Mathematics
    • Data sources
    • Content adapters
  • テンプレート
    • 本節
    • はじめに
    • Template types
    • Lookup order
    • 基本テンプレート
    • Home templates
    • Single templates
    • Section templates
    • Taxonomy templates
    • Term templates
    • 部分テンプレート
    • コンテントビューテンプレート
    • ショートコードテンプレート
    • サイトマップテンプレート
    • RSS テンプレート
    • 404 テンプレート
    • robots.txt templates
    • メニュー
    • ページネーション
    • Embedded templates
    • Custom output formats
  • 関数
    • 本節
    • cast
    • collections
    • compare
    • crypto
    • css
    • data
    • debug
    • diagrams
    • encoding
    • fmt
    • global
    • go template
    • hash
    • hugo
    • images
    • inflect
    • js
    • lang
    • math
    • openapi3
    • os
    • partials
    • path
    • reflect
    • resources
    • safe
    • strings
    • templates
    • time
    • transform
    • urls
  • メソッド
    • 本節
    • Duration
    • Menu
    • Menu entry
    • Page
    • Pager
    • Pages
    • Resource
    • Shortcode
    • Site
    • Taxonomy
    • Time
  • レンダーフック
    • 本節
    • Introduction
    • Blockquotes
    • Code blocks
    • Headings
    • Images
    • Links
    • Passthrough
    • Tables
  • Hugo モジュール
    • In this section
    • Configure Hugo modules
    • Use Hugo Modules
    • Theme components
  • Hugo パイプ
    • 本節
    • Introduction
    • Transpile Sass to CSS
    • PostCSS
    • PostProcess
    • JavaScript building
    • Babel
    • Asset minification
    • Concatenating assets
    • Fingerprinting and SRI hashing
    • Resource from string
    • Resource from template
  • CLI
  • トラブルシューティング
    • 本節
    • Logging
    • Inspection
    • Deprecation
    • Performance
    • FAQs
  • 開発ツール
    • 本節
    • Editor plugins
    • Front-ends
    • 検索
    • Migrations
    • Other projects
  • ホスティングと開発
    • 本節
    • Hugo Deploy
    • Deploy with Rclone
    • Deploy with Rsync
    • Host on 21YunBox
    • Host on AWS Amplify
    • Host on Azure Static Web Apps
    • Host on Cloudflare Pages
    • Host on Firebase
    • Host on GitHub Pages
    • Host on GitLab Pages
    • Host on KeyCDN
    • Host on Netlify
    • Host on Render
  • 貢献
    • 本節
    • Development
    • ドキュメント
    • Themes
  • メンテナンス
はじめよう 基本構成

Configure markup

Configure rendering of markup to HTML.

デフォルトハンドラー

Hugo は HTML へのマークダウンレンダリングに Goldmark を利用します。

hugo.
     
markup:
  defaultMarkdownHandler: goldmark
[markup]
  defaultMarkdownHandler = 'goldmark'
{
   "markup": {
      "defaultMarkdownHandler": "goldmark"
   }
}

ファイル拡張子が .md または .markdown であるものは、マークダウンの対象として処理されます。 ただしフロントマターの markup フィールドを通じて、別の コンテントフォーマット を指定することもできます。

マークダウンファイルに対して別のレンダラーを用いる際には、サイト設定ファイルにおいて asciidocext, org, pandoc, rst のいずれかを設定します。

マークダウンハンドラー 内容説明
asciidocext AsciiDoc
goldmark Goldmark
org Emacs Org Mode
pandoc Pandoc
rst reStructuredText

AsciiDoc, Pandoc, reStructuredText を利用する場合は、対応するレンダラーをインストールした上で、セキュリティポリシー を更新する必要があります。

Unless you need a unique capability provided by one of the alternate Markdown handlers, we strongly recommend that you use the default setting. Goldmark is fast, well maintained, conforms to the CommonMark specification, and is compatible with GitHub Flavored Markdown (GFM).

Goldmark

以下は Goldmark マークダウンレンダラーに対するデフォルト設定です。

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 extensions

The extensions below, excluding Extras and Passthrough, are enabled by default.

Extension Documentation Enabled
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

v0.126.0 の新機能

Enable deleted text, inserted text, mark text, subscript, and superscript elements in Markdown.

Element Markdown Rendered
Deleted text ~~foo~~ <del>foo</del>
Inserted text ++bar++ <ins>bar</ins>
Mark text ==baz== <mark>baz</mark>
Subscript H~2~O H<sub>2</sub>O
Superscript 1^st^ 1<sup>st</sup>

To avoid a conflict when enabling the Hugo Goldmark Extras subscript extension, if you want to render subscript and strikethrough text concurrently you must:

  1. Disable the Goldmark strikethrough extension
  2. Enable the Hugo Goldmark Extras delete extension

For example:

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

v0.122.0 の新機能

Enable the passthrough extension to include mathematical equations and expressions in Markdown using LaTeX or TeX typesetting syntax. See mathematics in Markdown for details.

Typographer

The Typographer extension replaces certain character combinations with HTML entities as specified below:

Markdown Replaced by Description
... &hellip; horizontal ellipsis
' &rsquo; apostrophe
-- &ndash; en dash
--- &mdash; em dash
« &laquo; left angle quote
“ &ldquo; left double quote
‘ &lsquo; left single quote
» &raquo; right angle quote
” &rdquo; right double quote
’ &rsquo; right single quote

Goldmark settings explained

Most of the Goldmark settings above are self-explanatory, but some require explanation.

duplicateResourceFiles
v0.123.0 の新機能

(bool) If true, shared page resources on multilingual single-host sites will be duplicated for each language. See multilingual page resources for details. Default is false.

With multilingual single-host sites, setting this parameter to false will enable Hugo’s embedded link render hook and embedded image render hook. This is the default configuration for multilingual single-host sites.

parser.wrapStandAloneImageWithinParagraph

(bool) If true, image elements without adjacent content will be wrapped within a p element when rendered. This is the default Markdown behavior. Set to false when using an image render hook to render standalone images as figure elements. Default is true.

parser.autoHeadingIDType

(string) The strategy used to automatically generate heading id attributes, one of github, github-ascii or blackfriday.

  • github produces GitHub-compatible id attributes
  • github-ascii drops any non-ASCII characters after accent normalization
  • blackfriday produces id attributes compatible with the Blackfriday Markdown renderer

This is also the strategy used by the anchorize template function. Default is github.

parser.attribute.block

(bool) If true, enables Markdown attributes for block elements. Default is false.

parser.attribute.title

(bool) If true, enables Markdown attributes for headings. Default is true.

renderHooks.image.enableDefault
v0.123.0 の新機能

(bool) If true, enables Hugo’s embedded image render hook. Default is false.

The embedded image render hook is automatically enabled for multilingual single-host sites if duplication of shared page resources is disabled. This is the default configuration for multilingual single-host sites.

renderHooks.link.enableDefault
v0.123.0 の新機能

(bool) If true, enables Hugo’s embedded link render hook. Default is false.

The embedded link render hook is automatically enabled for multilingual single-host sites if duplication of shared page resources is disabled. This is the default configuration for multilingual single-host sites.

renderer.hardWraps

(bool) If true, Goldmark replaces newline characters within a paragraph with br elements. Default is false.

renderer.unsafe

(bool) If true, Goldmark renders raw HTML mixed within the Markdown. This is unsafe unless the content is under your control. Default is false.

AsciiDoc

This is the default configuration for the AsciiDoc renderer:

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 settings explained

attributes

(map) A map of key-value pairs, each a document attributes. See Asciidoctor’s attributes.

backend

(string) The backend output file format. Default is html5.

extensions

(string array) An array of enabled extensions, one or more of asciidoctor-html5s, asciidoctor-bibtex, asciidoctor-diagram, asciidoctor-interdoc-reftext, asciidoctor-katex, asciidoctor-latex, asciidoctor-mathematical, or asciidoctor-question.

To mitigate security risks, entries in the extension array may not contain forward slashes (/), backslashes (\), or periods. Due to this restriction, extensions must be in Ruby’s $LOAD_PATH.

failureLevel

(string) The minimum logging level that triggers a non-zero exit code (failure). Default is fatal.

noHeaderOrFooter

(bool) If true, outputs an embeddable document, which excludes the header, the footer, and everything outside the body of the document. Default is true.

preserveTOC

(bool) If true, preserves the table of contents (TOC) rendered by Asciidoctor. By default, to make the TOC compatible with existing themes, Hugo removes the TOC rendered by Asciidoctor. To render the TOC, use the TableOfContents method on a Page object in your templates. Default is false.

safeMode

(string) The safe mode level, one of unsafe, safe, server, or secure. Default is unsafe.

sectionNumbers

(bool) If true, numbers each section title. Default is false.

trace

(bool) If true, include backtrace information on errors. Default is false.

verbose

(bool)If true, verbosely prints processing information and configuration file checks to stderr. Default is false.

workingFolderCurrent

(bool) If true, sets the working directory to be the same as that of the AsciiDoc file being processed, allowing includes to work with relative paths. Set to true to render diagrams with the asciidoctor-diagram extension. Default is false.

AsciiDoc configuration example

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 syntax highlighting

Follow the steps below to enable syntax highlighting.

Step 1
Set the source-highlighter attribute in your site configuration. For example:
hugo.
     
markup:
  asciidocExt:
    attributes:
      source-highlighter: rouge
[markup]
  [markup.asciidocExt]
    [markup.asciidocExt.attributes]
      source-highlighter = 'rouge'
{
   "markup": {
      "asciidocExt": {
         "attributes": {
            "source-highlighter": "rouge"
         }
      }
   }
}
Step 2
Generate the highlighter CSS. For example:
rougify style monokai.sublime > assets/css/syntax.css
Step 3
In your base template add a link to the CSS file:
layouts/_default/baseof.html
<head>
  ...
  {{ with resources.Get "css/syntax.css" }}
    <link rel="stylesheet" href="{{ .RelPermalink }}" integrity="{{ .Data.Integrity }}" crossorigin="anonymous">
  {{ end }}
  ...
</head>

Then add the code to be highlighted to your markup:

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

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

AsciiDoc troubleshooting

Run hugo --logLevel debug to examine Hugo’s call to the Asciidoctor executable:

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

This is the default highlight configuration. Note that some of these settings can be set per code block, see Syntax Highlighting.

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

For style, see these galleries:

  • Short snippets
  • Long snippets

For CSS, see Generate Syntax Highlighter CSS.

Table of contents

This is the default configuration for the table of contents, applicable to Goldmark and 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) Heading levels less than this value will be excluded from the table of contents. For example, to exclude h1 elements from the table of contents, set this value to 2. Default is 2.

endLevel

(int) Heading levels greater than this value will be excluded from the table of contents. For example, to exclude h4, h5, and h6 elements from the table of contents, set this value to 3. Default is 3.

ordered

(bool) If true, generates an ordered list instead of an unordered list. Default is false.

関連項目

  • コンテントフォーマット
  • Markdown attributes
  • ショートコード
  • Blockquote render hooks
  • Code block render hooks

このページ内

  • デフォルトハンドラー
  • Goldmark
  • AsciiDoc
  • Highlight
  • Table of contents
最終更新日付: 0001/01/01
ページの変更
Hugo 作者より
Hugo Logo
  • Issue 報告
  • ヘルプ
  • @GoHugoIO
  • @spf13
  • @bepsays
 

Hugo Sponsors

Route4Me
Your Company?
 

The Hugo logos are copyright © Steve Francia 2013–2024.

The Hugo Gopher is based on an original work by Renée French.

  • ニュース
  • ドキュメント
  • テーマ
  • コミュニティ
  • GitHub
  • Hugo について
  • インストール
  • はじめよう
  • クイックリファレンス
  • コンテント管理
  • テンプレート
  • 関数
  • メソッド
  • レンダーフック
  • Hugo モジュール
  • Hugo パイプ
  • CLI
  • トラブルシューティング
  • 開発ツール
  • ホスティングと開発
  • 貢献
  • メンテナンス