j2kun / hugo-goldmark-extensions

Work in progress.

Hugo Goldmark Extensions

This repository houses a collection of Goldmark extensions created by the Hugo community, focusing on expanding Hugo's markdown functionality.

Passthrough extension

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:

$a^*=x-b^*$

Delimiters

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.

Usage

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