markdown

README

This is an implementation of John Gruber's markdown in Go. It is a translation of peg-markdown, written by John MacFarlane in C, into Go. It is using a modified version of Andrew J Snodgrass' PEG parser peg -- now supporting LEG grammars --, which itself is based on the parser used by peg-markdown.

Support for HTML and groff mm output is implemented, but LaTeX output has not been ported. The output is identical to that of peg-markdown.

I try to keep the grammar in sync with the C version, by cherry-picking relevant changes. In the commit history the corresponding revisions have a suffix [jgm/peg-markdown].

The Markdown parser has a performance similar to that of the original C version, and consumes less memory.

Installation

Provided you have a copy of Go 1, and git is available,

go get github.com/knieriem/markdown

should download and install the package according to your GOPATH settings.

See doc.go for an example how to use the package.

---

To create the command line program markdown, run

go build github.com/knieriem/markdown/cmd/markdown

the binary should then be available in the current directory.

To run tests, type

go test github.com/knieriem/markdown

At the moment, tests are based on the .text files from the Markdown 1.0.3 test suite created by John Gruber, imported from peg-markdown. The output of the conversion of these .text files to html is compared to the output of peg-markdown.

Development

There is not yet a way to create a Go source file like parser.leg.go automatically from another file, parser.leg, when building packages and commands using the Go tool. To make markdown installable using go get, parser.leg.go has been added to the VCS.

Make parser will update parser.leg.go using leg – which is part of knieriem/peg at github –, if parser.leg has been changed, or if the Go file is missing. If a copy of peg is not yet present on your system, run

go get github.com/knieriem/peg

Then make parser should succeed.

Extensions

In addition to the extensions already present in peg-markdown, this package also supports definition lists (option -dlists) similar to the way they are described in the documentation of PHP Markdown Extra.

Definitions (<dd>...</dd>) are implemented using ListTight and ListLoose, on which bullet lists and ordered lists are based already. If there is an empty line between the definition title and the first definition, a loose list is expected, a tight list otherwise.

As definition item markers both : and ~ can be used.

Todo

• Port tables and perhaps other extensions from fletcher/peg-multimarkdown.

Subdirectory Index

• cmd/markdown – command line program markdown

Documentation

Overview

A translation of peg-markdown 1 into Go.

Usage example:

package main

import (
	"github.com/knieriem/markdown"
	"os"
	"bufio"
)

func main() {
	p := markdown.NewParser(&markdown.Extensions{Smart: true})

	w := bufio.NewWriter(os.Stdout)
	p.Markdown(os.Stdin, markdown.ToHTML(w))
	w.Flush()
}

Index

• Constants
• type Extensions
• type Formatter
  • func ToGroffMM(w Writer) Formatter
  • func ToHTML(w Writer) Formatter
• type Parser
  • func NewParser(x *Extensions) (p *Parser)
  • func (p *Parser) Markdown(src io.Reader, f Formatter)
• type Writer

Constants

const (
	LIST = iota /* A generic list of values. For ordered and bullet lists, see below. */
	RAW         /* Raw markdown to be processed further */
	SPACE
	LINEBREAK
	ELLIPSIS
	EMDASH
	ENDASH
	APOSTROPHE
	SINGLEQUOTED
	DOUBLEQUOTED
	STR
	LINK
	IMAGE
	CODE
	HTML
	EMPH
	STRONG
	STRIKE
	PLAIN
	PARA
	LISTITEM
	BULLETLIST
	ORDEREDLIST
	H1 /* Code assumes that H1..6 are in order. */
	H2
	H3
	H4
	H5
	H6
	BLOCKQUOTE
	VERBATIM
	HTMLBLOCK
	HRULE
	REFERENCE
	NOTE
	DEFINITIONLIST
	DEFTITLE
	DEFDATA
)

Types of semantic values returned by parsers.

const (
	TABSTOP = 4
)

Types

type Extensions

type Extensions struct {
	Smart        bool
	Notes        bool
	FilterHTML   bool
	FilterStyles bool
	Strike       bool
	Dlists       bool
}

Markdown Extensions.

type Formatter

type Formatter interface {
	FormatBlock(*element)
	Finish()
}

A Formatter is called repeatedly, one Markdown block at a time, while the document is parsed. At the end of a document the Finish method is called, which may, for example, print footnotes. A Formatter can be reused.

func ToGroffMM

func ToGroffMM(w Writer) Formatter

Returns a formatter that writes the document in groff mm format.

func ToHTML

func ToHTML(w Writer) Formatter

type Parser

type Parser struct {
	// contains filtered or unexported fields
}

func NewParser

func NewParser(x *Extensions) (p *Parser)

NewParser creates an instance of a parser. It can be reused so that stacks and buffers need not be allocated anew for each Markdown call.

func (*Parser) Markdown

func (p *Parser) Markdown(src io.Reader, f Formatter)

Markdown parses input from an io.Reader into a tree, and sends parsed blocks to a Formatter

type Writer

type Writer interface {
	Write([]byte) (int, error)
	WriteString(string) (int, error)
	WriteRune(rune) (int, error)
	WriteByte(byte) error
}