This repository houses a collection of Goldmark extensions created by the Hugo community, focusing on expanding Hugo's markdown functionality.
Use this extension to preserve raw Markdown within delimited snippets of text. This was initially developed to support LaTeX mixed with Markdown, specifically mathematical expressions and equations.
For example, to preserve raw Markdown for inline snippets delimited by the $
character:
Markdown | Default rendering | Passthrough rendering |
---|---|---|
a $_text_$ snippet |
a $<em>text</em>$ snippet |
a $_text_$ snippet |
In the Markdown example above, the underscores surrounding the word "text" signify emphasis. The Markdown renderer wraps the word within em
tags as required by the CommonMark specification. In comparison, the passthrough extension preserves the text within and including the delimiters.
Why is this important? Consider this example of a mathematical equation written in LaTeX:
Markdown | Default rendering | Passthrough rendering |
---|---|---|
$a^*=x-b^*$ |
$a^<em>=x-b^</em>$ |
$a^*=x-b^*$ |
Without this extension, LaTeX parsers such as KaTeX and MathJax will render this:
$a^=x-b^$
Instead of this:
There are two types of delimiters:
- Text within and including inline delimiters is rendered inline with the surrounding text.
- Text within and including block delimiters is rendered between adjacent block elements.
As shown below, delimiters are defined in pairs of opening and closing characters.
package main
import (
"bytes"
"fmt"
"github.com/gohugoio/hugo-goldmark-extensions/passthrough"
"github.com/yuin/goldmark"
)
func main() {
md := goldmark.New(
goldmark.WithExtensions(
passthrough.New(
passthrough.Config{
InlineDelimiters: []passthrough.Delimiters{
{
Open: "$",
Close: "$",
},
{
Open: "\\(",
Close: "\\)",
},
},
BlockDelimiters: []passthrough.Delimiters{
{
Open: "$$",
Close: "$$",
},
{
Open: "\\[",
Close: "\\]",
},
},
},
)),
)
input := `
block $$a^*=x-b^*$$ snippet
inline $a^*=x-b^*$ snippet
`
var buf bytes.Buffer
if err := md.Convert([]byte(input), &buf); err != nil {
panic(err)
}
fmt.Println(buf.String())
}
Use this extension to include inserted text, mark text, subscript, and superscript elements in Markdown.
Element | Markdown | Rendered |
---|---|---|
Inserted text | ++foo++ |
<ins>foo</ins> |
Mark text | ==bar== |
<mark>bar</mark> |
Subscript | H~2~O |
H<sub>2</sub>O |
Superscript | 1^st^ |
1<sup>st</sup> |
package main
import (
"bytes"
"fmt"
"github.com/gohugoio/hugo-goldmark-extensions/extras"
"github.com/yuin/goldmark"
)
func main() {
md := goldmark.New(
goldmark.WithExtensions(extras.New(
extras.Config{
Insert: extras.InsertConfig{Enable: true},
Mark: extras.MarkConfig{Enable: true},
Subscript: extras.SubscriptConfig{Enable: true},
Superscript: extras.SuperscriptConfig{Enable: true},
},
)),
)
input := `
Hydrogen (H) is the 1^st^ element in the periodic table.
Water (H~2~O) is a liquid.
Water (H~2~O) is a ++transparent++ liquid.
Water (H~2~O) is a ++transparent++ ==liquid==.
`
var buf bytes.Buffer
if err := md.Convert([]byte(input), &buf); err != nil {
panic(err)
}
fmt.Println(buf.String())
}