Home

flexmark-java

Java library for parsing and rendering Markdown text according to the CommonMark specification (and some extensions).

Provides classes for parsing input to an abstract syntax tree of nodes (AST), visiting and manipulating nodes, and rendering to HTML. It is a rework of commonmark-java to generate AST which allows recreating the original source, full source position references for all nodes and easier JetBrains Open API PsiTree generation.

It has a similar API to commonmark-java and many added extensions and enhancements to the core with the following features:

• Small (minimal dependencies)
• Fast, about 17 times faster than pegdown and 7 times faster than intellij-markdown only about 35%-40% slower than commonmark-java after adding easy source tracking
• Flexible (manipulate the AST after parsing, customize HTML rendering)
• Extensible (tables, strikethrough, autolinks and more, see below)
• Complete source position tracking in the AST with all source elements represented in the AST
• Extensible common options setting mechanism to allow easy parser, renderer and extension behaviour modification.
• Practically all behavior of the core parser can be modified, including the default InlineParser.

Requirements

• Java 8 or above
• The core has no dependencies; for extensions, see below

History

The motivation for creating this project was to replace pegdown as the parser for Markdown Navigator plugin for JetBrains line of IDEs. pegdown has many performance issues that cannot be resolved because of its implementation. Additionally, pegdown parsing of markdown elements interact with each other and it can only parse the full file with no ability to mark a spot beyond which no roll back should occur. For some sources this causes pegdown to go into exponential parse times and in a few cases into infinite parsing loops which could only be resolved by changing the grammar to be no longer markdown compatible.

Changes

Since I needed to implement a lot of extensions to make this parser a superset of pegdown I wanted to improve the ability of extensions to modify the behaviour of the parser to allow implementation of any markdown dialect through the extension mechanism. I also wanted to remove boiler plate code and make tests in extensions use the commonmark spec.txt format but with the addition of having the AST as part of the test so that the AST could be validated for every construct and every extension.

The end goal is to have a parser that can be easily extended to be compatible with:

• pegdown
• CommonMark
• GitHub Flavoured Markdown
• Kramdown
• MultiMarkdown
• PhpExtra

This is a work in progress with many API changes.

No attempt is made to keep backward compatibility to the original project.

Changes from commonmark-java project

• The project is not yet on Maven
• Java compatibility raised to 1.8 so that lambdas could be used to clean up HTML generation and make indented output easier
• Android compatibility neglected for now

Table of Contents

Usage
Extensions
Writing Extensions
Testing
Extensions To Do List
Basic Benchmarks