HUGO

  • News
  • Docs
  • Themes
  • Showcase
  • Community
  • GitHub
gohugoio Star

What's on this Page

  • Default configuration
  • Goldmark
  • Highlight
  • Table of contents
  • Markdown render hooks
FUNDAMENTALS GETTING STARTED

Configure markup

Configure rendering of markup to HTML.

Default configuration

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

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

hugo.
     
markup:
  asciidocExt:
    attributes: {}
    backend: html5
    extensions: []
    failureLevel: fatal
    noHeaderOrFooter: true
    preserveTOC: false
    safeMode: unsafe
    sectionNumbers: false
    trace: false
    verbose: false
    workingFolderCurrent: false
  defaultMarkdownHandler: goldmark
  goldmark:
    extensions:
      cjk:
        eastAsianLineBreaks: false
        enable: false
        escapedSpace: false
      definitionList: true
      footnote: true
      linkify: true
      linkifyProtocol: https
      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
    renderer:
      hardWraps: false
      unsafe: false
      xhtml: false
  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
  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.goldmark]
    [markup.goldmark.extensions]
      definitionList = true
      footnote = true
      linkify = true
      linkifyProtocol = 'https'
      strikethrough = true
      table = true
      taskList = true
      [markup.goldmark.extensions.cjk]
        eastAsianLineBreaks = false
        enable = false
        escapedSpace = false
      [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.renderer]
      hardWraps = false
      unsafe = false
      xhtml = false
  [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.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
      },
      "defaultMarkdownHandler": "goldmark",
      "goldmark": {
         "extensions": {
            "cjk": {
               "eastAsianLineBreaks": false,
               "enable": false,
               "escapedSpace": false
            },
            "definitionList": true,
            "footnote": true,
            "linkify": true,
            "linkifyProtocol": "https",
            "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
         },
         "renderer": {
            "hardWraps": false,
            "unsafe": false,
            "xhtml": false
         }
      },
      "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
      },
      "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.

This is the default configuration:

hugo.
     
markup:
  goldmark:
    extensions:
      cjk:
        eastAsianLineBreaks: false
        enable: false
        escapedSpace: false
      definitionList: true
      footnote: true
      linkify: true
      linkifyProtocol: https
      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
    renderer:
      hardWraps: false
      unsafe: false
      xhtml: false
[markup]
  [markup.goldmark]
    [markup.goldmark.extensions]
      definitionList = true
      footnote = true
      linkify = true
      linkifyProtocol = 'https'
      strikethrough = true
      table = true
      taskList = true
      [markup.goldmark.extensions.cjk]
        eastAsianLineBreaks = false
        enable = false
        escapedSpace = false
      [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.renderer]
      hardWraps = false
      unsafe = false
      xhtml = false
{
   "markup": {
      "goldmark": {
         "extensions": {
            "cjk": {
               "eastAsianLineBreaks": false,
               "enable": false,
               "escapedSpace": false
            },
            "definitionList": true,
            "footnote": true,
            "linkify": true,
            "linkifyProtocol": "https",
            "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
         },
         "renderer": {
            "hardWraps": false,
            "unsafe": false,
            "xhtml": false
         }
      }
   }
}

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

Some settings explained:

hardWraps
By default, Goldmark ignores newlines within a paragraph. Set to true to render newlines as <br> elements.
unsafe
By default, Goldmark does not render raw HTML 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.

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

Note that attributes in code fences must come after the opening tag, with any other highlighting processing instruction, e.g.:

```go {.myclass linenos=table,hl_lines=[8,"15-17"],linenostart=199}
// ... code
```
autoHeadingIDType (“github”)
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 compatible 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.

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

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

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
If true, generates an ordered list instead of an unordered list.

Markdown render hooks

See Markdown Render Hooks.

See also

  • Configure Hugo
  • Related content
  • Shortcodes
  • Syntax highlighting
  • About Hugo
    • Overview
    • What is Hugo
    • Hugo features
    • Static site generators
    • Hugo's security model
    • Hugo and the GDPR
    • License
  • Installation
    • Overview
    • macOS
    • Linux
    • Windows
    • BSD
  • Getting started
    • Overview
    • Quick start
    • Basic usage
    • Directory structure
    • Configuration
    • Configure markup
    • Glossary of terms
    • External learning resources
  • Hugo Modules
    • Overview
    • Configure Hugo modules
    • Use Hugo Modules
    • Theme components
  • Content management
    • Overview
    • Organization
    • Page bundles
    • Content formats
    • Diagrams
    • Front matter
    • Build options
    • Page resources
    • Image processing
    • Shortcodes
    • Related content
    • Sections
    • Content types
    • Archetypes
    • Taxonomies
    • Summaries
    • Links and cross references
    • URL management
    • Menus
    • Static files
    • Table of contents
    • Comments
    • Multilingual
    • Syntax highlighting
  • Templates
    • Overview
    • Templating
    • Template lookup order
    • Base templates and blocks
    • Single page templates
    • List templates
    • Homepage template
    • Section templates
    • Taxonomy templates
    • Pagination
    • Content view templates
    • Partial templates
    • Shortcode templates
    • Menu templates
    • Data templates
    • RSS templates
    • Sitemap templates
    • Local file templates
    • Internal templates
    • Render hooks
    • Custom output formats
    • 404 page
    • Robots.txt
    • Template debugging
  • Functions
    • Overview
    • .AddDate
    • .Format
    • .Get
    • .GetPage
    • .HasMenuCurrent
    • .IsMenuCurrent
    • .Param
    • .Render
    • .RenderString
    • .Scratch
    • .Store
    • .Unix
    • absLangURL
    • absURL
    • after
    • anchorize
    • append
    • apply
    • base64Decode
    • base64Encode
    • chomp
    • collections.Reverse
    • complement
    • cond
    • countrunes
    • countwords
    • crypto.FNV32a
    • debug.Dump
    • default
    • delimit
    • dict
    • duration
    • echoParam
    • emojify
    • eq
    • errorf
    • erroridf
    • fileExists
    • findRE
    • findRESubmatch
    • first
    • float
    • ge
    • getCSV
    • getenv
    • getJSON
    • group
    • gt
    • highlight
    • hmac
    • htmlEscape
    • htmlUnescape
    • hugo
    • humanize
    • i18n
    • Image filters
    • in
    • index
    • int
    • intersect
    • isset
    • jsonify
    • keyVals
    • lang.FormatAccounting
    • lang.FormatCurrency
    • lang.FormatNumber
    • lang.FormatNumberCustom
    • lang.FormatPercent
    • lang.Merge
    • last
    • le
    • len
    • lower
    • lt
    • markdownify
    • math
    • md5
    • merge
    • ne
    • newScratch
    • now
    • os.Stat
    • page
    • partial
    • partialCached
    • path.Base
    • path.BaseName
    • path.Clean
    • path.Dir
    • path.Ext
    • path.Join
    • path.Split
    • plainify
    • pluralize
    • print
    • printf
    • println
    • querify
    • range
    • readDir
    • readFile
    • ref
    • reflect.IsMap
    • reflect.IsSlice
    • relLangURL
    • relref
    • relURL
    • replace
    • replaceRE
    • safeCSS
    • safeHTML
    • safeHTMLAttr
    • safeJS
    • safeJSStr
    • safeURL
    • seq
    • sha1
    • sha256
    • shuffle
    • singularize
    • site
    • slice
    • slicestr
    • sort
    • split
    • string
    • strings.Contains
    • strings.ContainsAny
    • strings.ContainsNonSpace
    • strings.Count
    • strings.FirstUpper
    • strings.HasPrefix
    • strings.HasSuffix
    • strings.Repeat
    • strings.RuneCount
    • strings.TrimLeft
    • strings.TrimPrefix
    • strings.TrimRight
    • strings.TrimSuffix
    • substr
    • symdiff
    • templates.Exists
    • time
    • time.Format
    • time.ParseDuration
    • title
    • transform.CanHighlight
    • transform.HighlightCodeBlock
    • transform.Remarshal
    • transform.Unmarshal
    • trim
    • truncate
    • union
    • uniq
    • upper
    • urlize
    • urlquery
    • urls.JoinPath
    • urls.Parse
    • warnf
    • where
    • with
  • Variables
    • Overview
    • Site variables
    • Page variables
    • Shortcode variables
    • Pages methods
    • Taxonomy variables
    • File variables
    • Menu variables
    • Git variables
    • Sitemap variables
  • Hugo Pipes
    • Overview
    • 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
  • Troubleshooting
    • Overview
    • Frequently asked questions
    • Build performance
  • Developer tools
    • Overview
    • Editor plugins
    • Frontends
    • Search
    • Migrations
    • Other projects
  • Hosting and deployment
    • Overview
    • 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
  • Contribute
    • Overview
    • Development
    • Documentation
    • Themes
  • Maintenance
Last updated: September 30, 2023: Add return type to functions (a3a40ff9)
Improve this page
By the Hugo Authors
Hugo Logo
  • File an Issue
  • Get Help
  • @GoHugoIO
  • @spf13
  • @bepsays

Netlify badge

 

Hugo Sponsors

 

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

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

  • News
  • Docs
  • Themes
  • Showcase
  • Community
  • GitHub
  • About Hugo
  • Installation
  • Getting started
  • Hugo Modules
  • Content management
  • Templates
  • Functions
  • Variables
  • Hugo Pipes
  • CLI
  • Troubleshooting
  • Developer tools
  • Hosting and deployment
  • Contribute
  • Maintenance