mgodown

README

A Markdown Parser and HTML or Text Renderer for Go

It's fast and supports common extensions.

Installation

go get -u github.com/Feemic/mgodown

API Docs:

• /ast : defines abstract syntax tree of parsed markdown document
• /parser : parser
• /html : html renderer

Usage

To convert markdown text to HTML (split into heading and main content):

md := []byte("[TOC]\r\n## markdown document")

extensions := parser.CommonExtensions
mkparser := parser.NewWithExtensions(extensions)
htmlFlags := html.CommonFlags | html.TOC
opts := html.RendererOptions{Flags: htmlFlags}
renderer := html.NewRenderer(opts)

heading, content := mgodown.ToHTML(md, mkparser, renderer)

Extensions & Difference

Default option:no empty line before block are supported
Tables: tables are supported if there are spaces in the table header
MathJaX:
add display math block

n \geq 2^{\frac {h} {2}} - 1

History

mgodown is a fork of gomarkdown which is a fork of v2 of blackfriday

Blackfriday itself was based on C implementation sundown which in turn was based on libsoldout.

License

Simplified BSD License

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/Feemic/mgodown/parser"
	"github.com/Feemic/mgodown/renderer"
	"github.com/Feemic/mgodown"
)
extensions := parser.CommonExtensions | parser.AutoHeadingIDs
p := parser.NewWithExtensions(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/gomarkdown/mdtohtml

Index

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

Functions

func HeaderToHtml

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

feemic add:Just render header

func HeadingRender

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

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 Preparse

func Preparse(markdown []byte) []byte

feemic add:Pre process, hand line break etc.

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, []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.