Markdown Parser and HTML Renderer for Go

Package github.com/gomarkdown/markdown is a Go library for parsing Markdown text and rendering as HTML.

It's very fast, supports common extensions and has a CommonMark mode that passes all 652 examples of the CommonMark 0.31.2 spec.

Tutorial: https://blog.kowalczyk.info/article/cxn3/advanced-markdown-processing-in-go.html

Code examples:

• https://arslexis.io/goplayground/#txO7hJ-ibeU : basic markdown => HTML
• https://arslexis.io/goplayground/#yFRIWRiu-KL : customize HTML renderer
• https://arslexis.io/goplayground/#2yV5-HDKBUV : modify AST
• https://arslexis.io/goplayground/#9fqKwRbuJ04 : customize parser
• https://arslexis.io/goplayground/#Bk0zTvrzUDR : syntax highlight

Those examples are also in the examples directory.

API Docs:

• https://pkg.go.dev/github.com/gomarkdown/markdown : top level package
• https://pkg.go.dev/github.com/gomarkdown/markdown/ast : defines abstract syntax tree of parsed markdown document
• https://pkg.go.dev/github.com/gomarkdown/markdown/parser : parser
• https://pkg.go.dev/github.com/gomarkdown/markdown/html : html renderer
• https://pkg.go.dev/github.com/gomarkdown/markdown/md : markdown renderer, see Rendering to Markdown

Usage

To convert markdown text to HTML using reasonable defaults:

package main

import (
	"github.com/gomarkdown/markdown"
	"github.com/gomarkdown/markdown/html"
	"github.com/gomarkdown/markdown/parser"

	"fmt"
)

var mds = `# header

Sample text.

[link](http://example.com)
`

func mdToHTML(md []byte) []byte {
	// create markdown parser with extensions
	extensions := parser.CommonExtensions | parser.AutoHeadingIDs | parser.NoEmptyLineBeforeBlock
	p := parser.NewWithExtensions(extensions)
	doc := p.Parse(md)

	// create HTML renderer with extensions
	htmlFlags := html.CommonFlags | html.HrefTargetBlank
	opts := html.RendererOptions{Flags: htmlFlags}
	renderer := html.NewRenderer(opts)

	return markdown.Render(doc, renderer)
}

func main() {
	md := []byte(mds)
	html := mdToHTML(md)

	fmt.Printf("--- Markdown:\n%s\n\n--- HTML:\n%s\n", md, html)
}

Example source: examples/basic.go

CommonMark

parser.NewCommonMark() creates a parser for the CommonMark 0.31.2 grammar. It's a shortcut for setting the parser.CommonMark flag. All 652 official examples are tested against exact HTML output. The flag is off by default, preserving existing parsing and rendering behavior.

CommonMark mode uses this library's parser and usual ast nodes, so AST traversal, transformation, custom renderers, and HTML rendering hooks remain available. It uses strict CommonMark syntax regardless of the parser's Extensions setting; extensions and custom block/inline parsers apply only when the flag is off. Reference destination and title overrides remain available.

When markdown.ToHTML receives no renderer, CommonMark documents use XHTML tags and no smart punctuation, matching the official examples. To customize rendering, supply an html.Renderer with your own flags.

p := parser.NewCommonMark()
output := markdown.ToHTML([]byte("# Hello\n"), p, nil)

parser.NewCommonMarkWithExtensions(extensions) adds the extensions most documents need on top of CommonMark, following GitHub Flavored Markdown where it differs from the historical parser. Of extensions, those in parser.CommonMarkExtensions apply and the rest are ignored:

• parser.Tables: pipe tables, which can interrupt a paragraph
• parser.Strikethrough: ~~text~~
• parser.Autolink: bare http://, https://, ftp:// and mailto: URLs become links, without trailing punctuation or an unbalanced closing parenthesis
• parser.AutoHeadingIDs: heading ids made from the heading text

It also runs Opts.ParserHook at the start of each block, so custom block syntax works in CommonMark documents:

p := parser.NewCommonMarkWithExtensions(parser.CommonMarkExtensions)
p.Opts.ParserHook = myBlockParser
output := markdown.ToHTML(input, p, renderer)

For more documentation, read this guide

Rendering to Markdown

md.NewRenderer() renders an AST back to Markdown, for example to reformat a document or to write one after modifying its AST:

p := parser.NewWithExtensions(parser.CommonExtensions)
doc := p.Parse(input)
output := markdown.Render(doc, md.NewRenderer())

The output parses to the same HTML as the input, with the parser that read the input. It escapes whatever would otherwise be read as Markdown syntax. md.WithRenderInFooter(true) writes link destinations as reference definitions at the end of the document instead of inline.

The output is a normalized form of the input: the lines of a paragraph are joined, emphasis is written with *, headings with # and code blocks with fences. A few things don't round-trip: whitespace that HTML ignores anyway, the leading . of a code block's info string ({.go} is written as go), and emphasis nested three levels deep with punctuation next to the delimiters.

Comparing to other markdown parsers: https://babelmark.github.io/

Sanitize untrusted content

We don't protect against malicious content. When dealing with user-provided markdown, run the rendered HTML through an HTML sanitizer such as Bluemonday.

The HTML renderer has two flags for untrusted input, which reduce what a document can do but don't replace a sanitizer:

• html.SkipHTML removes raw HTML.
• html.Safelink restricts the URL scheme of links and images to http, https, ftp, mailto and relative paths. It doesn't check hosts (http://[email protected]/ is allowed) and doesn't affect raw HTML.

以上為 README 的開頭部分。其餘內容請閱讀原文。 檢視完整 README ↗