Skip to content
Package90 repository health

goldmark

A CommonMark-compliant Markdown parser and renderer for Go, built around a walkable AST and pluggable extensions.

Library Govv1.8.75,111 stars MIT License
go get github.com/yuin/goldmark
View source

Repository health

Pre-computed score based on development activity, maintenance, community, maturity, and trend momentum.How we score it →
Excellent
  • Development activity96
  • Maintenance100
  • Community64
  • Maturity60
  • Momentum40

Technical analysis

AI-assessed by reading the actual repository — architecture, code quality, innovation, and documentation.How we score it →
Excellent
  • Architecture88
  • Code quality90
  • Innovation78
  • Learning curve70

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.

Used by 17 apps in this directory

Every app whose dependencies include github.com/yuin/goldmark, nine to a page.

Showing 17 apps
TypeScript 50%Apache 2.0

agent-orchestrator

14,975

AI Agents · AI Code Assistants · Developer Tools

A local desktop workspace that gives every coding task its own agent, Git branch, and worktree, then tracks tasks, pull requests, CI, and reviews for 27 coding agents on one live Kanban board.

App
Built with
  • TypeScript 50%
  • Go 48%
Updated todayView details
Rust 55%MIT

Anarlog

9,945

AI Assistants · Note Taking · Productivity

Anarlog is an open-source, local-first AI meeting notetaker that records, transcribes, and summarizes meetings entirely on your device — no cloud lock-in, no mandatory account, and every note saved as a plain markdown file you own forever.

App
Built with
  • Rust 55%
  • TypeScript 32%
Updated todayView details
Go 61%Apache 2.0

Apache Answer

15,716

Community

Open-source Q&A platform for communities, help centers, and knowledge bases with AI assistant and plugin extensibility

App
Built with
  • Go 61%
  • TypeScript 36%
Updated 2 days agoView details
Go 99%Apache 2.0

Caddy

79,343

Devops · Security

The only web server that obtains and renews TLS certificates automatically, with HTTP/1-2-3 support and zero dependency on external runtimes.

App
Built with
  • Go 99%
Updated 2 days agoView details
Go 74%AGPL 3.0

Coder

17,450

Code Editors · Developer Tools · Devops

Self-hosted cloud development environments and AI coding agents — defined in Terraform, connected via WireGuard, automatically shut down when idle.

App
Built with
  • Go 74%
  • TypeScript 24%
Updated todayView details
Go 84%AGPL 3.0

Cozy Stack

1,267

File Storage · Productivity

Self-hosted personal cloud platform that unifies your files, apps, and devices in one private space you fully control.

App
Built with
  • Go 84%
  • TypeScript 10%
Updated yesterdayView details
Go 83%MIT

Gitea

59,197

Developer Tools · Devops · Project Management

Self-hosted DevOps in a single Go binary — Git hosting, GitHub Actions-compatible CI/CD, and 30+ package registries without any SaaS dependency.

App
Built with
  • Go 83%
Updated todayView details
Go 63%Apache 2.0

Harness Open Source

38,948

Code Editors · Developer Tools · Devops

A unified open source DevOps platform combining Git hosting, CI/CD pipelines, cloud development environments, and artifact registries in a single self-hosted system.

App
Built with
  • Go 63%
  • TypeScript 33%
Updated yesterdayView details
Go 50%AGPL 3.0

listmonk

24,399

Blogging · Marketing

High-performance, self-hosted newsletter and mailing list manager packaged as a single binary with built-in analytics, transactional messaging, and multi-channel delivery.

App
Built with
  • Go 50%
  • JavaScript 22%
  • HTML 21%
Updated 6 days agoView details

Join founders building with open source

Opinionated takes, migration guides, cost-saving tips, and insights from the open source ecosystem.

Subscribe on SubstackJoin 750+ subscribers