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:

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:

Without this extension, LaTeX parsers such as KaTeX and MathJax will render this:

$a^=x-b^$

Instead of this:

$a^*=x-b^*$

There are two types of delimiters, inline and block:

• Text within and including inline delimiters appears inline with the surrounding text.
• Text within and including block delimiters appears between adjacent block elements. When working with LaTeX this is known as display mode.

As shown below, you must specify zero or more inline and block delimiter pairs—there are no default values.

package main

import (
	"bytes"
	"fmt"

	"github.com/gohugoio/hugo-goldmark-extensions/passthrough"
	"github.com/yuin/goldmark"
)

func main() {
	inlineDelimiters := []passthrough.Delimiters{
		{Open: "\\(", Close: "\\)"},
	}
	blockDelimiters := []passthrough.Delimiters{
		{Open: "\\[", Close: "\\]"},
		{Open: "$$", Close: "$$"},
	}

	md := goldmark.New(
		goldmark.WithExtensions(
			passthrough.NewPassthroughWithDelimiters(
				inlineDelimiters,
				blockDelimiters,
			)),
	)

	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())
}