Configure markup 配置标记

Default handler #

Hugo uses [Goldmark] to render Markdown to HTML.

markup:
  defaultMarkdownHandler: goldmark

[markup]
  defaultMarkdownHandler = 'goldmark'

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

Files with a .md, .mdown, or .markdown extension are processed as Markdown, provided that you have not specified a different [content format] using the markup field in front matter.

To use a different renderer for Markdown files, specify one of asciidocext, org, pandoc, or rst in your site configuration.

To use AsciiDoc, Pandoc, or reStructuredText you must install the relevant renderer and update your [security policy].

Goldmark #

This is the default configuration for the Goldmark Markdown renderer:

Goldmark extensions #

The extensions below,

excluding Extras and Passthrough, are enabled by default.

Extras #

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

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:

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 #

Enable the passthrough extension to include mathematical equations and expressions in Markdown using LaTeX markup. See [mathematics in Markdown] for details.

Typographer #

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

Goldmark settings explained #

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

duplicateResourceFiles #

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

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 #

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

renderHooks.link.enableDefault #

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

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:

markup:
  asciidocExt: null

[markup]

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

AsciiDoc settings explained #

attributes #

(map) A map of key-value pairs, each a document attribute. 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.

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 #

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:

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:

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

markup:
  highlight: null

[markup]

{
   "markup": {
      "highlight": null
   }
}

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:

markup:
  tableOfContents: null

[markup]

{
   "markup": {
      "tableOfContents": null
   }
}

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.