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:

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
  defaultMarkdownHandler: goldmark
  goldmark:
    extensions:
      definitionList: true
      footnote: true
      linkify: true
      strikethrough: true
      table: true
      taskList: true
      typographer: true
    parser:
      attribute: true
      autoHeadingID: true
    renderer:
      hardWraps: false
      unsafe: false
      xHTML: false
  highlight:
    codeFences: true
    hl_Lines: ""
    lineNoStart: 1
    lineNos: false
    lineNumbersInTable: true
    noClasses: true
    style: monokai
    tabWidth: 4
  tableOfContents:
    endLevel: 3
    startLevel: 2

[markup]
  defaultMarkdownHandler = "goldmark"
  [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]
      attribute = true
      autoHeadingID = true
    [markup.goldmark.renderer]
      hardWraps = false
      unsafe = false
      xHTML = false
  [markup.highlight]
    codeFences = true
    hl_Lines = ""
    lineNoStart = 1
    lineNos = false
    lineNumbersInTable = true
    noClasses = true
    style = "monokai"
    tabWidth = 4
  [markup.tableOfContents]
    endLevel = 3
    startLevel = 2

{
   "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
      },
      "defaultMarkdownHandler": "goldmark",
      "goldmark": {
         "extensions": {
            "definitionList": true,
            "footnote": true,
            "linkify": true,
            "strikethrough": true,
            "table": true,
            "taskList": true,
            "typographer": true
         },
         "parser": {
            "attribute": true,
            "autoHeadingID": true
         },
         "renderer": {
            "hardWraps": false,
            "unsafe": false,
            "xHTML": false
         }
      },
      "highlight": {
         "codeFences": true,
         "hl_Lines": "",
         "lineNoStart": 1,
         "lineNos": false,
         "lineNumbersInTable": true,
         "noClasses": true,
         "style": "monokai",
         "tabWidth": 4
      },
      "tableOfContents": {
         "endLevel": 3,
         "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:

config.

markup:
  goldmark:
    extensions:
      definitionList: true
      footnote: true
      linkify: true
      strikethrough: true
      table: true
      taskList: true
      typographer: true
    parser:
      attribute: true
      autoHeadingID: true
    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]
      attribute = true
      autoHeadingID = 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": true,
            "autoHeadingID": true
         },
         "renderer": {
            "hardWraps": false,
            "unsafe": false,
            "xHTML": false
         }
      }
   }
}

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.

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:

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.

config.

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

[markup]
  [markup.highlight]
    codeFences = true
    hl_Lines = ""
    lineNoStart = 1
    lineNos = false
    lineNumbersInTable = true
    noClasses = true
    style = "monokai"
    tabWidth = 4

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

For style, see these galleries:

For CSS, see Generate Syntax Highlighter CSS.

config.

markup:
  tableOfContents:
    endLevel: 3
    startLevel: 2

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

{
   "markup": {
      "tableOfContents": {
         "endLevel": 3,
         "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.

Configure Markup