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:
Those examples are also in the examples directory.
API Docs:
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 paragraphparser.Strikethrough: ~~text~~parser.Autolink: bare http://, https://, ftp:// and mailto: URLs become links, without trailing punctuation or an unbalanced closing parenthesisparser.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 전문 보기 ↗
