hugo/docs/content/en/getting-started/configuration-markup.md
2020-06-02 19:02:10 +02:00

6.5 KiB

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.
autoHeadingIDType ("github") {{< new-in "0.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:

{{< 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:

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.

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

The features currently supported are:

  • image
  • link
  • heading {{< new-in "0.71.0" >}}

You can define Output-Format- and language-specific templates if needed.1 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.
[Text](https://www.gohugo.io "Title")

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

{{< code file="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 }} {{< /code >}}

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:

{{< code file="layouts/_default/_markup/render-image.html" >}}

{{ .Text }}

{{< /code >}}

Given this template file

{{< code file="layouts/_default/_markup/render-heading.html" >}} <h{{ .Level }} id="{{ .Anchor | safeURL }}">{{ .Text | safeHTML }} ¶</h{{ .Level }}> {{< /code >}}

And this markdown

### Section A

The rendered html will be

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

  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. ↩︎