Configure Markup

How to handle Markdown and other markup related configuration.

Configure Markup

See Goldmark for settings related to the default Markdown handler in Hugo.

Below are all markup related configuration in Hugo with their default settings:

markup:
  asciidocExt:
    attributes: {}
    backend: html5
    extensions: []
    failureLevel: fatal
    noHeaderOrFooter: true
    preserveTOC: false
    safeMode: unsafe
    sectionNumbers: false
    trace: false
    verbose: false
    workingFolderCurrent: false
  blackFriday:
    angledQuotes: false
    extensions: null
    extensionsMask: null
    footnoteAnchorPrefix: ""
    footnoteReturnLinkContents: ""
    fractions: true
    hrefTargetBlank: false
    latexDashes: true
    nofollowLinks: false
    noreferrerLinks: false
    plainIDAnchors: true
    skipHTML: false
    smartDashes: true
    smartypants: true
    smartypantsQuotesNBSP: false
    taskLists: true
  defaultMarkdownHandler: goldmark
  goldmark:
    extensions:
      definitionList: true
      footnote: true
      linkify: true
      strikethrough: true
      table: true
      taskList: true
      typographer: true
    parser:
      attribute:
        block: false
        title: true
      autoHeadingID: true
      autoHeadingIDType: github
    renderer:
      hardWraps: false
      unsafe: false
      xhtml: false
  highlight:
    anchorLineNos: false
    codeFences: true
    guessSyntax: false
    hl_Lines: ""
    lineAnchors: ""
    lineNoStart: 1
    lineNos: false
    lineNumbersInTable: true
    noClasses: true
    style: monokai
    tabWidth: 4
  tableOfContents:
    endLevel: 3
    ordered: false
    startLevel: 2

[markup]
  defaultMarkdownHandler = 'goldmark'
  [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.blackFriday]
    angledQuotes = false
    footnoteAnchorPrefix = ''
    footnoteReturnLinkContents = ''
    fractions = true
    hrefTargetBlank = false
    latexDashes = true
    nofollowLinks = false
    noreferrerLinks = false
    plainIDAnchors = true
    skipHTML = false
    smartDashes = true
    smartypants = true
    smartypantsQuotesNBSP = false
    taskLists = true

  [markup.goldmark]
    [markup.goldmark.extensions]
      definitionList = true
      footnote = true
      linkify = true
      strikethrough = true
      table = true
      taskList = true
      typographer = true

    [markup.goldmark.parser]
      autoHeadingID = true
      autoHeadingIDType = 'github'
      [markup.goldmark.parser.attribute]
        block = false
        title = true


    [markup.goldmark.renderer]
      hardWraps = false
      unsafe = false
      xhtml = false


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

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

{
   "markup": {
      "asciidocExt": {
         "attributes": {},
         "backend": "html5",
         "extensions": [],
         "failureLevel": "fatal",
         "noHeaderOrFooter": true,
         "preserveTOC": false,
         "safeMode": "unsafe",
         "sectionNumbers": false,
         "trace": false,
         "verbose": false,
         "workingFolderCurrent": false
      },
      "blackFriday": {
         "angledQuotes": false,
         "extensions": null,
         "extensionsMask": null,
         "footnoteAnchorPrefix": "",
         "footnoteReturnLinkContents": "",
         "fractions": true,
         "hrefTargetBlank": false,
         "latexDashes": true,
         "nofollowLinks": false,
         "noreferrerLinks": false,
         "plainIDAnchors": true,
         "skipHTML": false,
         "smartDashes": true,
         "smartypants": true,
         "smartypantsQuotesNBSP": false,
         "taskLists": true
      },
      "defaultMarkdownHandler": "goldmark",
      "goldmark": {
         "extensions": {
            "definitionList": true,
            "footnote": true,
            "linkify": true,
            "strikethrough": true,
            "table": true,
            "taskList": true,
            "typographer": true
         },
         "parser": {
            "attribute": {
               "block": false,
               "title": true
            },
            "autoHeadingID": true,
            "autoHeadingIDType": "github"
         },
         "renderer": {
            "hardWraps": false,
            "unsafe": false,
            "xhtml": false
         }
      },
      "highlight": {
         "anchorLineNos": false,
         "codeFences": true,
         "guessSyntax": false,
         "hl_Lines": "",
         "lineAnchors": "",
         "lineNoStart": 1,
         "lineNos": false,
         "lineNumbersInTable": true,
         "noClasses": true,
         "style": "monokai",
         "tabWidth": 4
      },
      "tableOfContents": {
         "endLevel": 3,
         "ordered": false,
         "startLevel": 2
      }
   }
}

See each section below for details.

Goldmark

Goldmark is from Hugo 0.60 the default library used for Markdown. It’s fast, it’s CommonMark compliant and it’s very flexible. Note that the feature set of Goldmark vs Blackfriday isn’t the same; you gain a lot but also lose some, but we will work to bridge any gap in the upcoming Hugo versions.

This is the default configuration:

markup:
  goldmark:
    extensions:
      definitionList: true
      footnote: true
      linkify: true
      strikethrough: true
      table: true
      taskList: true
      typographer: true
    parser:
      attribute:
        block: false
        title: true
      autoHeadingID: true
      autoHeadingIDType: github
    renderer:
      hardWraps: false
      unsafe: false
      xhtml: false

[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      definitionList = true
      footnote = true
      linkify = true
      strikethrough = true
      table = true
      taskList = true
      typographer = true

    [markup.goldmark.parser]
      autoHeadingID = true
      autoHeadingIDType = 'github'
      [markup.goldmark.parser.attribute]
        block = false
        title = true


    [markup.goldmark.renderer]
      hardWraps = false
      unsafe = false
      xhtml = false

{
   "markup": {
      "goldmark": {
         "extensions": {
            "definitionList": true,
            "footnote": true,
            "linkify": true,
            "strikethrough": true,
            "table": true,
            "taskList": true,
            "typographer": true
         },
         "parser": {
            "attribute": {
               "block": false,
               "title": true
            },
            "autoHeadingID": true,
            "autoHeadingIDType": "github"
         },
         "renderer": {
            "hardWraps": false,
            "unsafe": false,
            "xhtml": false
         }
      }
   }
}

For details on the extensions, refer to this section of the Goldmark documentation

Some settings explained:

unsafe: By default, Goldmark does not render raw HTMLs and potentially dangerous links. If you have lots of inline HTML and/or JavaScript, you may need to turn this on.
typographer: This extension substitutes punctuations with typographic entities like smartypants .
attribute: Enable custom attribute support for titles and blocks by adding attribute lists inside single curly brackets ({.myclass class="class1 class2" }) and placing it after the Markdown element it decorates, on the same line for titles and on a new line directly below for blocks.

New in v0.81 In Hugo 0.81.0 we added support for adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc.

A blockquote with a CSS class:

> foo
> bar
{.myclass}

There are some current limitations: For tables you can currently only apply it to the full table, and for lists the ul/ol-nodes only, e.g.:

* Fruit
  * Apple
  * Orange
  * Banana
  {.fruits}
* Dairy
  * Milk
  * Cheese
  {.dairies}
{.list}

autoHeadingIDType (“github”) New in v0.62.2: The strategy used for creating auto IDs (anchor names). Available types are github, github-ascii and blackfriday. github produces GitHub-compatible IDs, github-ascii will drop any non-Ascii characters after accent normalization, and blackfriday will make the IDs work as with Blackfriday , the default Markdown engine before Hugo 0.60. Note that if Goldmark is your default Markdown engine, this is also the strategy used in the anchorize template func.

Blackfriday

Blackfriday was Hugo’s default Markdown rendering engine, now replaced with Goldmark. But you can still use it: Just set defaultMarkdownHandler to blackfriday in your top level markup config.

This is the default config:

markup:
  blackFriday:
    angledQuotes: false
    extensions: null
    extensionsMask: null
    footnoteAnchorPrefix: ""
    footnoteReturnLinkContents: ""
    fractions: true
    hrefTargetBlank: false
    latexDashes: true
    nofollowLinks: false
    noreferrerLinks: false
    plainIDAnchors: true
    skipHTML: false
    smartDashes: true
    smartypants: true
    smartypantsQuotesNBSP: false
    taskLists: true

[markup]
  [markup.blackFriday]
    angledQuotes = false
    footnoteAnchorPrefix = ''
    footnoteReturnLinkContents = ''
    fractions = true
    hrefTargetBlank = false
    latexDashes = true
    nofollowLinks = false
    noreferrerLinks = false
    plainIDAnchors = true
    skipHTML = false
    smartDashes = true
    smartypants = true
    smartypantsQuotesNBSP = false
    taskLists = true

{
   "markup": {
      "blackFriday": {
         "angledQuotes": false,
         "extensions": null,
         "extensionsMask": null,
         "footnoteAnchorPrefix": "",
         "footnoteReturnLinkContents": "",
         "fractions": true,
         "hrefTargetBlank": false,
         "latexDashes": true,
         "nofollowLinks": false,
         "noreferrerLinks": false,
         "plainIDAnchors": true,
         "skipHTML": false,
         "smartDashes": true,
         "smartypants": true,
         "smartypantsQuotesNBSP": false,
         "taskLists": true
      }
   }
}

Highlight

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

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

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

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

For style, see these galleries:

For CSS, see Generate Syntax Highlighter CSS .

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

These settings only works for the Goldmark renderer:

startLevel: The heading level, values starting at 1 (h1), to start render the table of contents.
endLevel: The heading level, inclusive, to stop render the table of contents.
ordered: Whether or not to generate an ordered list instead of an unordered list.

Markdown Render Hooks

New in v0.62.0

Note that this is only supported with the Goldmark renderer.

Render Hooks allow custom templates to override markdown rendering functionality. You can do this by creating templates with base names render-{feature} in layouts/_default/_markup.

You can also create type/section specific hooks in layouts/[type/section]/_markup, e.g.: layouts/blog/_markup. New in v0.71.0

The features currently supported are:

image
link
heading New in v0.71.0

You can define Output-Format- and language- specific templates if needed. Your layouts folder may look like this:

layouts
└── _default
    └── _markup
        ├── render-image.html
        ├── render-image.rss.xml
        └── render-link.html

Some use cases for the above:

Resolve link references using .GetPage. This would make links portable as you could translate ./my-post.md (and similar constructs that would work on GitHub) into /blog/2019/01/01/my-post/ etc.
Add target=_blank to external links.
Resolve and process images.
Add header links .

Render Hook Templates

The render-link and render-image templates will receive this context:

Page: The Page being rendered.
Destination: The URL.
Title: The title attribute.
Text: The rendered (HTML) link text.
PlainText: The plain variant of the above.

The render-heading template will receive this context:

Page: The Page being rendered.
Level: The header level (1–6)
Anchor: An auto-generated html id unique to the header within the page
Text: The rendered (HTML) text.
PlainText: The plain variant of the above.

Link with title Markdown example:

[Text](https://www.gohugo.io "Title")

Here is a code example for how the render-link.html template could look:

layouts/_default/_markup/render-link.html


<a href="{{ .Destination | safeURL }}"{{ with .Title}} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a>

Image Markdown example:

![Text](https://d33wubrfki0l68.cloudfront.net/c38c7334cc3f23585738e40334284fddcaf03d5e/2e17c/images/hugo-logo-wide.svg "Title")

Here is a code example for how the render-image.html template could look:

layouts/_default/_markup/render-image.html


<p class="md__image">
  <img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title}} title="{{ . }}"{{ end }} />
</p>

Heading link example

Given this template file

layouts/_default/_markup/render-heading.html


<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} <a href="#{{ .Anchor | safeURL }}">¶</a></h{{ .Level }}>

And this markdown

### Section A

The rendered html will be

<h3 id="section-a">Section A <a href="#section-a">¶</a></h3>