markdown

README

goldmark-markdown

Goldmark renderer, that renders goldmark AST back into markdown. Can be useful for programmatic markdown editing or formatting.

Goal:

Rendered markdown should be semantically equivalent to the original markdown parsed by goldmark.

In practice, it means that markdown input -> goldmark parser AST -> goldmark HTML render and markdown input -> goldmark parser AST -> goldmark-markdown rendered markdown -> goldmark parser AST -> goldmark HTML render should be identical, since the canonical markdown target is HTML.

Features:

• Correctly renders all examples in commonmark 0.31.2 spec.

• Correctly renders all examples in GitHub Flavored Markdown 0.29 spec

• Correctly renders a wide variety of markdown documents.

• Supports rendering all markdown elements

  • TODO: indented code blocks are replaced by fenced code blocks. It's hard to calculate appropriate padding that doesn't conflict with lazy list continuations.

• Supports rendering all GitHub Flavored Markdown elements

• Handles all edge cases.

  • Known issue: not all emphasis rules are followed, some unnatural nested emphasis sequences change their meaning.
  • Currently, the escaping is overly eager

• In-depth customization. Choose your preferred heading, hr, code block styles, emphasis characters, etc.

Example

go build ./examples/mdformat
./mdformat -i README.md -o README2.md

Documentation

Index

• Variables
• func NewRenderer(opts ...options.Option) *mdrenderer.Renderer
• func WithIgnoredNodes(kind ...ast.NodeKind) options.Option
• func WithThematicBreaks(breaks ...string) options.Option

Variables

var (
	IncorrectOptionError   = options.ErrIncorrectOption
	UnsupportedOptionError = options.ErrUnsupportedOption
)

Functions

func NewRenderer

func NewRenderer(opts ...options.Option) *mdrenderer.Renderer

NewRenderer returns a new renderer. Use [goldmark.WithExtensions] to add it to a goldmark instance.

func WithIgnoredNodes

func WithIgnoredNodes(kind ...ast.NodeKind) options.Option

WithIgnoredNodes sets up the renderer to ignore a node, proceeding to render its children

func WithThematicBreaks

func WithThematicBreaks(breaks ...string) options.Option

WithThematicBreaks sets the thematic break tags to use, in the order of preference