mirror of
https://github.com/gohugoio/hugo.git
synced 2024-11-14 20:37:55 -05:00
26f1458a2d
bd0e15bb6 Optimised images with calibre/image-actions 59830ea44 Remove comments from quickstart code samples 348821b5d Remove image-actions 1cbbd26a9 Update index.md bcf3de764 Update index.md fcf17e6ef Release 0.62.1 0956bde21 Merge branch 'temp621' 28d604756 releaser: Add release notes to /docs for release of 0.62.1 c895f12e7 Fix statement about version installed with apt-get (#854) e96928e38 Updated quickstart to split theme download and theme config add into separate blocks (#967) e099c1ad6 changed ".Title" to ".URL" (#972) bea71280d Fix small typing error (#1001) 9c28c422e Correct hyperlink for 'markdownify' function cf3844a06 Corrected small conjugation mistake (#996) 8b9c1d4f2 Added remarks about additional parameters in ref/relref (#995) ca06c9a56 Fix illegal character in render-link.html example 7a85c789b Update RenderString.md 69df3b17e Update configuration-markup.md 43e9222a2 Revert "Add shortcodes to note comparing with `markdownify`" 2bd5bc2d7 Add shortcodes to note comparing with `markdownify` ddfee60b7 Update configuration-markup.md f87c35fe2 docs: Remove extra double quotation 5ca5cc15f Update index.md 6e457f5ec Update configuration-markup.md 12df3c0fc Update configuration-markup.md 91977fd96 Update configuration-markup.md 377b8954a Update configuration-markup.md 99d691b5e Update hosting-on-render.md ccf855b22 Update index.md a945acc42 Update index.md 7d4f308d6 Fix Netlify config f4caa07f5 Release 0.62.0 79d18276f releaser: Add release notes to /docs for release of 0.62.0 9db1a08d1 Merge commit '8a4005cf2b0ef34265ff8051a6b76226685fc226' 79e556223 docs: More on hooks 5088c54df tpl: Do not return any value in errorf 98c8c8638 tpl: Add a warnf template func 4a9d76cea docs: Regen docshelper 626e53b55 Fix incorrect MIME type from image/jpg to image/jpeg f92f77c5d Preserve HTML Text for link render hooks 6db9c52b1 docs: Footnote 16801db3b Add render template hooks for links and images 0facb823c Merge commit '2e711a28c71e8667258e5ab824f9b9a71c261b0a' 79bf8ed4c markup/tableofcontents: Add config option for ordered list git-subtree-dir: docs git-subtree-split: bd0e15bb6063f7ad4f0c47eb33c8c0c23c962d13
138 lines
4.5 KiB
Markdown
138 lines
4.5 KiB
Markdown
---
|
|
title: Configure Markup
|
|
description: How to handle Markdown and other markup related configuration.
|
|
date: 2019-11-15
|
|
categories: [getting started,fundamentals]
|
|
keywords: [configuration,highlighting]
|
|
weight: 65
|
|
sections_weight: 65
|
|
slug: configuration-markup
|
|
toc: true
|
|
---
|
|
|
|
## Configure Markup
|
|
|
|
{{< new-in "0.60.0" >}}
|
|
|
|
See [Goldmark](#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](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.
|
|
|
|
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](https://daringfireball.net/projects/smartypants/).
|
|
|
|
### Blackfriday
|
|
|
|
|
|
[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.
|
|
|
|
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](/content-management/syntax-highlighting/).
|
|
|
|
{{< code-toggle config="markup.highlight" />}}
|
|
|
|
For `style`, see these galleries:
|
|
|
|
* [Short snippets](https://xyproto.github.io/splash/docs/all.html)
|
|
* [Long snippets](https://xyproto.github.io/splash/docs/longer/all.html)
|
|
|
|
For CSS, see [Generate Syntax Highlighter CSS](/content-management/syntax-highlighting/#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](#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/_markup`.
|
|
|
|
You can define [Output-Format-](/templates/output-formats) and [language-](/content-management/multilingual/)specific templates if needed.[^hooktemplate] Your `layouts` folder may look like this:
|
|
|
|
```bash
|
|
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](/content-management/image-processing/) images.
|
|
|
|
### Render Hook Templates
|
|
|
|
Both `render-link` and `render-image` templates will receive this context:
|
|
|
|
Page
|
|
: The [Page](/variables/page/) being rendered.
|
|
|
|
Destination
|
|
: The URL.
|
|
|
|
Title
|
|
: The title attribute.
|
|
|
|
Text
|
|
: The rendered (HTML) link text.
|
|
|
|
PlainText
|
|
: The plain variant of the above.
|
|
|
|
A Markdown example for an inline-style link with title:
|
|
|
|
```md
|
|
[Text](https://www.gohugo.io "Title")
|
|
```
|
|
|
|
A very simple template example given the above:
|
|
|
|
{{< code file="layouts/_default/_markup/render-link.html" >}}
|
|
<a href="{{ .Destination | safeURL }}"{{ with .Title}} title="{{ . }}"{{ end }}{{ if strings.HasPrefix .Destination "http" }} target="_blank"{{ end }}>{{ .Text }}</a>
|
|
{{< /code >}}
|
|
|
|
[^hooktemplate]: 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.
|
|
|