goldmark

A Markdown parser written in Go. Easy to extend, standards-compliant, well-structured.

goldmark is compliant with CommonMark 0.31.2.

• goldmark playground : Try goldmark online. This playground is built with WASM(5-10MB).

There is also a Rust version of goldmark: rushdown

Motivation

I needed a Markdown parser for Go that satisfies the following requirements:

• Easy to extend.
  • Markdown is poor in document expressions compared to other light markup languages such as reStructuredText.
  • We have extensions to the Markdown syntax, e.g. PHP Markdown Extra, GitHub Flavored Markdown.
• Standards-compliant.
  • Markdown has many dialects.
  • GitHub-Flavored Markdown is widely used and is based upon CommonMark, effectively mooting the question of whether or not CommonMark is an ideal specification.
    • CommonMark is complicated and hard to implement.
• Well-structured.
  • AST-based; preserves source position of nodes.
• Written in pure Go.

golang-commonmark may be a good choice, but it seems to be a copy of markdown-it.

blackfriday.v2 is a fast and widely-used implementation, but is not CommonMark-compliant and cannot be extended from outside of the package, since its AST uses structs instead of interfaces.

Furthermore, its behavior differs from other implementations in some cases, especially regarding lists: Deep nested lists don't output correctly #329, List block cannot have a second line #244, etc.

This behavior sometimes causes problems. If you migrate your Markdown text from GitHub to blackfriday-based wikis, many lists will immediately be broken.

As mentioned above, CommonMark is complicated and hard to implement, so Markdown parsers based on CommonMark are few and far between.

Features

• Standards-compliant. goldmark is fully compliant with the latest CommonMark specification.
• Extensible. Do you want to add a @username mention syntax to Markdown? You can easily do so in goldmark. You can add your AST nodes, parsers for block-level elements, parsers for inline-level elements, transformers for paragraphs, transformers for the whole AST structure, and renderers.
• Performance. goldmark's performance is on par with that of cmark, the CommonMark reference implementation written in C.
• Robust. goldmark is tested with go test --fuzz.
• Built-in extensions. goldmark ships with common extensions like tables, strikethrough, task lists, and definition lists.
• Depends only on standard libraries.

Installation

$ go get github.com/yuin/goldmark

Usage

Import packages:

import (
    "bytes"
    "github.com/yuin/goldmark"
)

Convert Markdown documents with the CommonMark-compliant mode:

var buf bytes.Buffer
if err := goldmark.Convert(source, &buf); err != nil {
  panic(err)
}

With options

var buf bytes.Buffer
if err := goldmark.Convert(source, &buf, parser.WithContext(ctx)); err != nil {
  panic(err)
}

| Functional option | Type | Description | | ----------------- | ---- | ----------- | | parser.WithContext | A parser.Context | Context for the parsing phase. |

Context options

| Functional option | Type | Description | | ----------------- | ---- | ----------- | | parser.WithIDs | A parser.IDs | IDs allows you to change logics that are related to element id(ex: Auto heading id generation). |

Custom parser and renderer

import (
    "bytes"
    "github.com/yuin/goldmark"
    "github.com/yuin/goldmark/extension"
    "github.com/yuin/goldmark/parser"
    "github.com/yuin/goldmark/renderer/html"
)

md := goldmark.New(
          goldmark.WithExtensions(extension.GFM),
          goldmark.WithParserOptions(
              parser.WithAutoHeadingID(),
          ),
          goldmark.WithRendererOptions(
              html.WithHardWraps(),
              html.WithXHTML(),
          ),
      )
var buf bytes.Buffer
if err := md.Convert(source, &buf); err != nil {
    panic(err)
}

| Functional option | Type | Description | | ----------------- | ---- | ----------- | | goldmark.WithParser | parser.Parser | This option must be passed before goldmark.WithParserOptions and goldmark.WithExtensions | | goldmark.WithRenderer | renderer.Renderer | This option must be passed before goldmark.WithRendererOptions and goldmark.WithExtensions | | goldmark.WithParserOptions | ...parser.Option | | | goldmark.WithRendererOptions | ...renderer.Option | | | goldmark.WithExtensions | ...goldmark.Extender | |

Parser and Renderer options

Parser options

| Functional option | Type | Description | | ----------------- | ---- | ----------- | | parser.WithBlockParsers | A util.PrioritizedSlice whose elements are parser.BlockParser | Parsers for parsing block level elements. | | parser.WithInlineParsers | A util.PrioritizedSlice whose elements are parser.InlineParser | Parsers for parsing inline level elements. | | parser.WithParagraphTransformers | A util.PrioritizedSlice whose elements are parser.ParagraphTransformer | Transformers for transforming paragraph nodes. | | parser.WithASTTransformers | A util.PrioritizedSlice whose elements are parser.ASTTransformer | Transformers for transforming an AST. | | parser.WithAutoHeadingID | - | Enables auto heading ids. | | parser.WithAttribute | - | Enables custom attributes. Currently only headings supports attributes. |

HTML Renderer options

| Functional option | Type | Description | | ----------------- | ---- | ----------- | | html.WithWriter | html.Writer | html.Writer for writing contents to an io.Writer. | | html.WithHardWraps | - | Render newlines as <br>.| | html.WithXHTML | - | Render as XHTML. | | html.WithUnsafe | - | By default, goldmark does not render raw HTML or potentially dangerous links. With this option, goldmark renders such content as written. |

Built-in extensions

• extension.Table
  • GitHub Flavored Markdown: Tables
• extension.Strikethrough
  • GitHub Flavored Markdown: Strikethrough
• extension.Linkify
  • GitHub Flavored Markdown: Autolinks
• extension.TaskList
  • GitHub Flavored Markdown: Task list items
• extension.GFM
  • This extension enables Table, Strikethrough, Linkify and TaskList.
  • This extension does not filter tags defined in 6.11: Disallowed Raw HTML (extension). If you need to filter HTML tags, see Security.
  • If you need to parse github emojis, you can use goldmark-emoji extension.
• extension.DefinitionList
  • PHP Markdown Extra: Definition lists
• extension.Footnote
  • PHP Markdown Extra: Footnotes
• extension.Typographer
  • This extension substitutes punctuations with typographic entities like smartypants.
• extension.CJK
  • This extension is a shortcut for CJK related functionalities.

Attributes

The parser.WithAttribute option allows you to define attributes on some elements.

Currently only headings support attributes.

Attributes are being discussed in the CommonMark forum. This syntax may possibly change in the future.

Headings

## heading ## {#id .className attrName=attrValue class="class1 class2"}

## heading {#id .className attrName=attrValue class="class1 class2"}

heading {#id .className attrName=attrValue}
============

Table extension

The Table extension implements Table(extension), as defined in GitHub Flavored Markdown Spec.

Specs are defined for XHTML, so specs use some deprecated attributes for HTML5.

You can override alignment rendering method via options.

| Functional option | Type | Description | | ----------------- | ---- | ----------- | | extension.WithTableCellAlignMethod | extension.TableCellAlignMethod | Option indicates how are table cells aligned. |

Typographer extension

The Typographer extension translates plain ASCII punctuation characters into typographic-punctuation HTML entities.

Default substitutions are:

| Punctuation | Default en