1--- 2title: Configure Markup 3description: How to handle Markdown and other markup related configuration. 4date: 2019-11-15 5categories: [getting started,fundamentals] 6keywords: [configuration,highlighting] 7weight: 65 8sections_weight: 65 9slug: configuration-markup 10toc: true 11--- 12 13## Configure Markup 14 15{{< new-in "0.60.0" >}} 16 17See [Goldmark](#goldmark) for settings related to the default Markdown handler in Hugo. 18 19Below are all markup related configuration in Hugo with their default settings: 20 21{{< code-toggle config="markup" />}} 22 23**See each section below for details.** 24 25### Goldmark 26 27[Goldmark](https://github.com/yuin/goldmark/) is from Hugo 0.60 the default library used for Markdown. It's fast, it's [CommonMark](https://spec.commonmark.org/0.29/) 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. 28 29This is the default configuration: 30 31{{< code-toggle config="markup.goldmark" />}} 32 33For details on the extensions, refer to [this section](https://github.com/yuin/goldmark/#built-in-extensions) of the Goldmark documentation 34 35Some settings explained: 36 37unsafe 38: 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. 39 40typographer 41: This extension substitutes punctuations with typographic entities like [smartypants](https://daringfireball.net/projects/smartypants/). 42 43attribute 44: 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. 45 46{{< new-in "0.81.0" >}} In Hugo 0.81.0 we added support for adding attributes (e.g. CSS classes) to Markdown blocks, e.g. tables, lists, paragraphs etc. 47 48A blockquote with a CSS class: 49 50```md 51> foo 52> bar 53{.myclass} 54``` 55 56There 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.: 57 58```md 59* Fruit 60 * Apple 61 * Orange 62 * Banana 63 {.fruits} 64* Dairy 65 * Milk 66 * Cheese 67 {.dairies} 68{.list} 69``` 70 71Note that attributes in [code fences](/content-management/syntax-highlighting/#highlighting-in-code-fences) must come after the opening tag, with any other highlighting processing instruction, e.g.: 72 73```` 74```go {.myclass linenos=table,hl_lines=[8,"15-17"],linenostart=199} 75// ... code 76``` 77```` 78 79autoHeadingIDType ("github") {{< new-in "0.62.2" >}} 80: 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](#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](/functions/anchorize/) template func. 81 82### Blackfriday 83 84 85[Blackfriday](https://github.com/russross/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. 86 87This is the default config: 88 89{{< code-toggle config="markup.blackFriday" />}} 90 91### Highlight 92 93This is the default `highlight` configuration. Note that some of these settings can be set per code block, see [Syntax Highlighting](/content-management/syntax-highlighting/). 94 95{{< code-toggle config="markup.highlight" />}} 96 97For `style`, see these galleries: 98 99* [Short snippets](https://xyproto.github.io/splash/docs/all.html) 100* [Long snippets](https://xyproto.github.io/splash/docs/longer/all.html) 101 102For CSS, see [Generate Syntax Highlighter CSS](/content-management/syntax-highlighting/#generate-syntax-highlighter-css). 103 104### Table Of Contents 105 106{{< code-toggle config="markup.tableOfContents" />}} 107 108These settings only works for the Goldmark renderer: 109 110startLevel 111: The heading level, values starting at 1 (`h1`), to start render the table of contents. 112 113endLevel 114: The heading level, inclusive, to stop render the table of contents. 115 116ordered 117: Whether or not to generate an ordered list instead of an unordered list. 118 119 120## Markdown Render Hooks 121 122{{< new-in "0.62.0" >}} 123 124Note that this is only supported with the [Goldmark](#goldmark) renderer. 125 126Render 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`. 127 128You can also create type/section specific hooks in `layouts/[type/section]/_markup`, e.g.: `layouts/blog/_markup`.{{< new-in "0.71.0" >}} 129 130The features currently supported are: 131 132* `image` 133* `link` 134* `heading` {{< new-in "0.71.0" >}} 135 136You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed. Your `layouts` folder may look like this: 137 138```bash 139layouts 140└── _default 141 └── _markup 142 ├── render-image.html 143 ├── render-image.rss.xml 144 └── render-link.html 145``` 146 147Some use cases for the above: 148 149* 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. 150* Add `target=_blank` to external links. 151* Resolve and [process](/content-management/image-processing/) images. 152* Add [header links](https://remysharp.com/2014/08/08/automatic-permalinks-for-blog-posts). 153 154### Render Hook Templates 155 156The `render-link` and `render-image` templates will receive this context: 157 158Page 159: The [Page](/variables/page/) being rendered. 160 161Destination 162: The URL. 163 164Title 165: The title attribute. 166 167Text 168: The rendered (HTML) link text. 169 170PlainText 171: The plain variant of the above. 172 173The `render-heading` template will receive this context: 174 175Page 176: The [Page](/variables/page/) being rendered. 177 178Level 179: The header level (1--6) 180 181Anchor 182: An auto-generated html id unique to the header within the page 183 184Text 185: The rendered (HTML) text. 186 187PlainText 188: The plain variant of the above. 189 190Attributes (map) {{< new-in "0.82.0" >}} 191: A map of attributes (e.g. `id`, `class`) 192 193#### Link with title Markdown example: 194 195```md 196[Text](https://www.gohugo.io "Title") 197``` 198 199Here is a code example for how the render-link.html template could look: 200 201{{< code file="layouts/_default/_markup/render-link.html" >}} 202<a href="{{ .Destination | safeURL }}"{{ with .Title}} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank" rel="noopener"{{ end }}>{{ .Text | safeHTML }}</a> 203{{< /code >}} 204 205#### Image Markdown example: 206 207```md 208![Text](https://d33wubrfki0l68.cloudfront.net/c38c7334cc3f23585738e40334284fddcaf03d5e/2e17c/images/hugo-logo-wide.svg "Title") 209``` 210 211Here is a code example for how the render-image.html template could look: 212 213{{< code file="layouts/_default/_markup/render-image.html" >}} 214<p class="md__image"> 215 <img src="{{ .Destination | safeURL }}" alt="{{ .Text }}" {{ with .Title}} title="{{ . }}"{{ end }} /> 216</p> 217{{< /code >}} 218 219#### Heading link example 220 221Given this template file 222 223{{< code file="layouts/_default/_markup/render-heading.html" >}} 224<h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} <a href="#{{ .Anchor | safeURL }}">¶</a></h{{ .Level }}> 225{{< /code >}} 226 227And this markdown 228 229```md 230### Section A 231``` 232 233The rendered html will be 234 235```html 236<h3 id="section-a">Section A <a href="#section-a">¶</a></h3> 237``` 238