hugo/docs/content/en/getting-started/configuration-markup.md

title	description	date	categories	keywords	weight	sections_weight	slug	toc
Configure Markup	How to handle Markdown and other markup related configuration.	2019-11-15	getting started fundamentals	configuration highlighting	65	65	configuration-markup	true

Configure Markup

{{< new-in "0.60.0" >}}

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

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

{{< code-toggle config="markup" />}}

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:

{{< code-toggle config="markup.goldmark" />}}

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:

{{< code-toggle config="markup.blackFriday" />}}

Highlight

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

{{< code-toggle config="markup.highlight" />}}

For style, see these galleries:

• Short snippets
• Long snippets

For CSS, see Generate Syntax Highlighter CSS.

Table Of Contents

{{< code-toggle config="markup.tableOfContents" />}}

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

Note that this is only supported with the Goldmark renderer.

These Render Hooks allow custom templates to render links and images from markdown.

You can do this by creating templates with base names render-link and/or render-image inside layouts/_default.

You can define Output Format specific templates if needed.¹ Your layouts folder may then 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 more 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 (look in the page bundle, inside /assets etc.) and transform images.

Render Hook Templates

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

Page

The Page being rendered.

Destination

The URL.

Title

The title attribute.

Text

The link text.

A Markdown example for a inline-style link with title:

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

A very simple template example given the above:

{{< code file="layouts/_default/render-link.html" >}} <a href="{{ .Destination | safeURL }}"{{ with .Title}}title="{{ . }}"{{ end }}>{{ .Text }}{{ with .Page }} (in page {{ .Title }}){{ end }}" {{< /code >}}

---

1. It's currently only possible to have one set of render hook templates, e.g. not per Type or Section. We may consider that in a future version. ↩︎