markdown

README

Markdown Parser and HTML Renderer for Go

Please go to the original author for the documentation: https://github.com/gomarkdown/markdown.

Documentation

Overview

Package markdown implements markdown parser and HTML renderer.

It parses markdown into AST format which can be serialized to HTML (using html.Renderer) or possibly other formats (using alternate renderers).

Convert markdown to HTML

The simplest way to convert markdown document to HTML

md := []byte("## markdown document")
html := markdown.ToHTML(md, nil, nil)

Customizing parsing and HTML rendering

You can customize parser and HTML renderer:

import (
	"github.com/rveen/markdown/parser"
	"github.com/rveen/markdown/renderer"
	"github.com/rveen/markdown"
)
extensions := parser.CommonExtensions | parser.AutoHeadingIDs
p := parser.NewWithExensions(extensions)

htmlFlags := html.CommonFlags | html.HrefTargetBlank
opts := html.RendererOptions{Flags: htmlFlags}
renderer := html.NewRenderer(opts)

md := []byte("markdown text")
html := markdown.ToHTML(md, p, renderer)

For a cmd-line tool see https://github.com/rveen/mdtohtml

Index

• func Parse(markdown []byte, p *parser.Parser) ast.Node
• func Render(doc ast.Node, renderer Renderer) []byte
• func ToHTML(markdown []byte, p *parser.Parser, renderer Renderer) []byte
• type Renderer

Functions

func Parse

func Parse(markdown []byte, p *parser.Parser) ast.Node

Parse parsers a markdown document using provided parser. If parser is nil, we use parser configured with parser.CommonExtensions.

It returns AST (abstract syntax tree) that can be converted to another format using Render function.

func Render

func Render(doc ast.Node, renderer Renderer) []byte

Render uses renderer to convert parsed markdown document into a different format.

To convert to HTML, pass html.Renderer

func ToHTML

func ToHTML(markdown []byte, p *parser.Parser, renderer Renderer) []byte

ToHTML converts markdownDoc to HTML.

You can optionally pass a parser and renderer. This allows to customize a parser, use a customized html render or use completely custom renderer.

If you pass nil for both, we use parser configured with parser.CommonExtensions and html.Renderer configured with html.CommonFlags.

Types

type Renderer

type Renderer interface {
	// RenderNode renders markdown node to w.
	// It's called once for a leaf node.
	// It's called twice for non-leaf nodes:
	// * first with entering=true
	// * then with entering=false
	//
	// Return value is a way to tell the calling walker to adjust its walk
	// pattern: e.g. it can terminate the traversal by returning Terminate. Or it
	// can ask the walker to skip a subtree of this node by returning SkipChildren.
	// The typical behavior is to return GoToNext, which asks for the usual
	// traversal to the next node.
	RenderNode(w io.Writer, node ast.Node, entering bool) ast.WalkStatus

	// RenderHeader is a method that allows the renderer to produce some
	// content preceding the main body of the output document. The header is
	// understood in the broad sense here. For example, the default HTML
	// renderer will write not only the HTML document preamble, but also the
	// table of contents if it was requested.
	//
	// The method will be passed an entire document tree, in case a particular
	// implementation needs to inspect it to produce output.
	//
	// The output should be written to the supplied writer w. If your
	// implementation has no header to write, supply an empty implementation.
	RenderHeader(w io.Writer, ast ast.Node)

	// RenderFooter is a symmetric counterpart of RenderHeader.
	RenderFooter(w io.Writer, ast ast.Node)
}

Renderer is an interface for implementing custom renderers.