vfmd

README

Vanilla Flavored Markdown (vfmd) Parser in Go

vfmd (Vanilla Flavored Markdown) is a sane Markdown variant with an unambiguous specification of syntax. This package is a pure-Go implementation of a parser for vfmd, with additional design goals and some more specific characteristics listed below:

Goals

• Adhere to the vfmd spec (fixing it as needed);
  • Done, with a notable exception of inline HTML;
  • Any assumed issues found in process reported as a pull request;
• Allow for any custom renderers, by outputting an intermediate format ("AST");
  • Done, a flattened tree representation is generated;
  • As an example and proof of concept, a HTML renderer is provided;
• Provide end-to-end mapping from input characters to the final parsed form (this can make it useful e.g. for syntax-highlighting);
  • Partially done: fulfilled for blocks, still TODO for spans (I tried to prepare for that, but it may well need API changes, so possibly this may require creating a new version, i.e. vfmd.v2 or later);
• Allow quick top-level-only parsing (e.g. to scan headers in order to build a Table of Contents);
  • Done;
• Pure Go;
  • Done;
• Try to determine worst-case efficiency (and then maybe try to reduce it);
  • TODO;
  • (Note: I think it should be possible to have it at least as good as amortized O(nmk²), where n is number of lines, m is deepest nesting level of blocks, and k is length of the longest paragraph (more strictly, text span sequence). But I absolutely haven't confirmed yet if the current code has such efficiency characteristics.)

More detailed characteristics

• Extensible syntax (thanks to the vfmd spec) ― both for block- and span-level markup;
  • As an example, subpackage x/mdgithub provides some extensions from GitHub-flavored Markdown: strikethrough with ~~ and fenced code blocks with triple backtick. The cmd/vfmd sample application shows how to enable those (when executed with --github flag).
  • TODO: add tables support from GH-flavored MD too.
• Quite well-tested (thanks to the vfmd testsuite);
• Does not support inline HTML (at least currently; this is arguably a feature for some use cases, like desktop editors or comment systems);
• Does not support inline HTML entities (like & etc.) ― Unicode should make up for that;
• TODO: the QuickHTML renderer does not currently filter URLs in links to protect against e.g. JavaScript "bookmarklet" attacks;
• FIXME: detect md.HardBreak tag for lines ending with " \n";
• FIXME: godoc
• FIXME: example in README
• FIXME: add tests for GitHub-flavored Markdown extensions;
• FIXME: true Region information in spans (vfmd.v2?)
• TODO: make DefaultDetectors comparable?
• TODO: add SmartyPants extensions (also, <a name="..." /> anchors if not there);
• TODO: add tests from Blackfriday too;

Documentation

Index

• func QuickHTML(w io.Writer, blocks []md.Tag) error
• func QuickPrep(r io.Reader) ([]byte, error)
• type Chunk
  • func (c Chunk) SourceLength() int
• type ChunkType
• type Preprocessor
  • func (p *Preprocessor) Close() error
  • func (p *Preprocessor) Write(buf []byte) (int, error)
  • func (p *Preprocessor) WriteByte(b byte) error

Functions

func QuickHTML

func QuickHTML(w io.Writer, blocks []md.Tag) error

func QuickPrep

func QuickPrep(r io.Reader) ([]byte, error)

Types

type Chunk

type Chunk struct {
	Type ChunkType
	// Bytes contains fragment of new data of the document (after
	// preprocessing).
	Bytes []byte
}

func (Chunk) SourceLength

func (c Chunk) SourceLength() int

SourceLength returns length of the byte slice in the original stream that was converted into this Chunk.

type ChunkType

type ChunkType int

const (
	ChunkIgnoredBOM ChunkType = iota
	ChunkUnchangedRunes
	ChunkIgnoredCR   // Note: only for CR immediately before LF
	ChunkUnchangedLF // Note: all LFs (for easier lines splitting)
	ChunkExpandedTab
	ChunkConvertedISO8859_1
)

type Preprocessor

type Preprocessor struct {
	Chunks  []Chunk
	Pending []byte
	// contains filtered or unexported fields
}

func (*Preprocessor) Close

func (p *Preprocessor) Close() error

func (*Preprocessor) Write

func (p *Preprocessor) Write(buf []byte) (int, error)

func (*Preprocessor) WriteByte

func (p *Preprocessor) WriteByte(b byte) error