goldmark

goldmark is a pure-Go Markdown parser and HTML renderer that fully implements the CommonMark specification while staying easy to extend. Rather than converting text directly to output, it builds an intermediate AST that preserves source positions, so callers can inspect, transform, or re-render the parsed document before it becomes HTML.

Every stage of the pipeline is a set of prioritized, swappable components: block parsers, inline parsers, paragraph transformers, AST transformers, and node renderers are all registered as ordered lists, so third-party extensions can slot new syntax (custom node kinds, new inline delimiters, new renderer funcs) in alongside the built-ins without forking the library. It ships built-in extensions for GitHub Flavored Markdown (tables, strikethrough, autolinks, task lists), PHP Markdown Extra style definition lists and footnotes, a typographer for smart punctuation, and CJK-aware line breaking.

By default goldmark does not render raw HTML or unsafe URLs, leaving that decision explicit via renderer options, and it is validated against the full CommonMark spec test suite plus Go’s native fuzzer. It has become the de facto Markdown engine for a large share of the Go ecosystem, including Hugo.

What You Get

• A CommonMark 0.31.2-compliant block and inline parser producing a walkable, position-preserving AST
• A default HTML renderer plus a renderer.NodeRenderer interface for building renderers to other formats
• Built-in GFM extensions: tables, strikethrough, autolinks (linkify), and task lists, bundled as extension.GFM
• Definition lists and footnotes matching PHP Markdown Extra syntax
• A typographer extension for smart quotes/dashes and a CJK extension for East Asian line-breaking rules
• Priority-ordered extension points for adding custom block parsers, inline parsers, paragraph/AST transformers, and node renderers
• Heading attribute syntax ({#id .class attr=value}) via parser.WithAttribute
• Safe-by-default HTML output that strips raw HTML and dangerous URLs unless explicitly opted into

Common Use Cases

• Static site generators - converting Markdown content files to HTML at build time with GFM-flavored tables and task lists
• Documentation tooling - rendering README/docs Markdown into HTML with custom heading IDs and sanitized output for embedding in a web UI
• Custom Markdown dialects - adding project-specific inline syntax (e.g. @mentions, custom shortcodes) by registering new inline parsers and AST node kinds
• Non-HTML rendering - walking the parsed AST to emit PDF, plain text, or another markup format instead of HTML by swapping in a custom NodeRenderer
• Comment/wiki systems - parsing untrusted user Markdown safely by default (no raw HTML passthrough) while selectively allowing GFM extensions

Under The Hood

Architecture

goldmark separates conversion into three composable stages wired together by the Markdown interface in markdown.go: a parser.Parser that turns a text.Reader into an ast.Node tree, and a renderer.Renderer that walks that tree to produce output. Both the parser and renderer are built from util.PrioritizedSlice registries — block parsers, inline parsers, paragraph transformers, AST transformers, and node renderers are all registered with numeric priorities (e.g. util.Prioritized(html.NewRenderer(), 1000)), so ordering and precedence between built-in and third-party components is explicit and deterministic rather than hardcoded. Extensions implement a single Extend(Markdown) method (see extension/gfm.go, extension/footnote.go) and hook themselves into any of these registries, which is what lets extension.GFM bundle four independent extensions (Table, Strikethrough, Linkify, TaskList) without any special-casing in the core. The ast package defines node kinds as an interface hierarchy (ast/block.go, ast/inline.go) rather than concrete structs, which is the specific design choice that makes external packages able to define wholly new node types goldmark itself never anticipated.

Tech Stack

goldmark is written in pure Go (module github.com/yuin/goldmark, Go 1.22+ per CI, though go.mod in this snapshot targets a newer toolchain) with zero runtime dependencies outside the standard library — the entire parser, AST, renderer, and extension set is self-contained across the ast, parser, renderer (with an html subpackage), text, and util packages. util/html5entities.gen.go and util/unicode_case_folding.gen.go are code-generated tables (HTML5 entity references and Unicode case folding) rather than hand-maintained data, keeping spec compliance mechanical to update. The project builds no CLI or server component; it is consumed purely as an importable library, and a separate WASM build powers the online playground referenced in the README.

Code Quality

The repo carries close to twenty _test.go files at the package root and within parser, ast, and extension, including commonmark_test.go and extra_test.go which run the official CommonMark spec fixtures (_test/spec.json) plus goldmark-specific edge cases (_test/extra.txt, _test/options.txt) through table-driven tests. A dedicated fuzz/ package wires goldmark.New with the full extension set into Go’s native fuzz testing (f.Fuzz), directly supporting the README’s “tested with go test —fuzz” claim. CI (.github/workflows/test.yaml) runs the suite with coverage across three Go versions and three OS platforms (Ubuntu/macOS/Windows) and reports to Coveralls, and golangci-lint runs with an explicit multi-linter set (errcheck, gosimple, govet, ineffassign, staticcheck, unused) enforced only on non-Windows runners to dodge CRLF false positives. Error handling favors returned error values over panics in the public API (Convert returns an error), and the codebase is idiomatically typed with no use of reflection-heavy patterns in the hot parsing path.

What Makes It Unique

goldmark’s distinguishing choice is treating the AST as a first-class, externally extensible interface rather than an implementation detail — competing Go Markdown libraries either aren’t CommonMark-compliant or expose concrete structs that block third-party node types, which the README calls out directly as a limitation of blackfriday.v2. Combined with the prioritized-registry extension model, this lets goldmark hit CommonMark 0.31.2 compliance, GFM feature parity, and cmark-comparable performance simultaneously, while remaining safe-by-default (no raw HTML/dangerous URL rendering without an explicit opt-in) — a combination the project’s own benchmarks and security section position as its core value proposition against alternatives like blackfriday and golang-commonmark.