markdown

Markdown parsing and rendering

AttrProvider	Extension point for adding/changing attributes on HTML tags for a node.
Delimited	A node that uses delimiters in the source form, e.g.
DelimiterProcessor	Custom delimiter processor for additional delimiters besides _ and *.
InlineContentParser	Parser for a type of inline content.
InlineContentParserFactory	A factory for extending inline content parsing.
InlineParser	Parser for inline content (text, links, emphasized text, etc.)
InlineParserState	InlineParserState
LinkInfo	A parsed link/image.
LinkProcessor	A mixin to decide how links/images are handled
MarkdownExt	Mixin for parser/renderer extensions.
NodeRenderer	A renderer for a set of node types
ParserState	Block parsing state.
PostProcessor	PostProcessors are run as the last step of parsing and provide an opportunity to inspect/modify the parsed AST before rendering.
Renderer	Renders a tree of nodes
UrlSanitizer	Sanitizes uris for img and a elements by whitelisting protocols.
Visitor	Node visitor

Block	A block node.
BlockContinue	Resulting object for continuing parsing of a block.
BlockParser	A block parser is able to parse a specific block node.
BlockParserFactory	Parser factory for a block node for determining when a block starts.
BlockQuote	Block quote block
BlockStart	Resulting object for starting parsing of a block.
BulletList	Bullet list block
Code	Code
CommonMarkSpecTest	Runs all the tests from the common mark specification
CustomBlock	Custom Block
CustomNode	Custom node
DefinitionMap	A map that can be used to store and lookup reference definitions by a label.
Delimiter	Delimiter (emphasis, strong emphasis, or custom emphasis)
Document	Document is the root node of the AST
Emphasis	Emphasis
FencedCode	Fenced code block
HardLineBreak	Hard line break
Heading	Heading block
HtmlBlock	HTML block
HtmlContext	Context for rendering nodes to HTML
HtmlInline	HTML inline
HtmlRenderer	Renders a tree of nodes to HTML
HtmlRendererBuilder	Builder for configuring an HtmlRenderer.
HtmlWriter	HTML writer for markdown rendering
Image	Image node
ImgAttrs	ImgAttrs
ImgAttrsExt	Extension for adding attributes to image nodes.
IndentedCode	Indented code block
InlineParserContext	InlineParserContext
Link	A link with a destination and an optional title; the link text is in child nodes
LinkNode	Base class for Link and Image nodes
LinkReferenceDefinition	A link reference definition
LinkResult	LinkResult
ListBlock	Abstract base class for list blocks
ListItem	List item
MarkdownContext	Context for rendering nodes to Markdown
MarkdownRenderer	Renders nodes to Markdown (CommonMark syntax).
MarkdownRendererBuilder	Builder for configuring a MarkdownRenderer
MarkdownWriter	Writer for Markdown (CommonMark) text.
MatchedBlockParser	Open block parser that was last matched during the continue phase.
Node	Base class for all CommonMark AST nodes.
OrderedList	Ordered list block
Paragraph	Paragraph
ParsedInline	ParsedInline
Parser	Parse input text into a tree of nodes.
ParserBuilder	Builder for customizing the behavior of the common mark parser
Position	A position in the Scanner consists of its line index (i.e.
Scanner	Scanner is a utility class for parsing lines
SoftLineBreak	Soft line break
SourceLine	A line or portion of a line from the markdown source text
SourceLines	A set of lines (SourceLine) from the input source.
SourceSpan	References a snippet of text from the source input.
SourceSpans	A list of source spans that can be added to.
StrongEmphasis	Strong emphasis
Table	Table block containing a TableHead and optionally a TableBody
TableBody	Body part of a Table containing TableRows
TableCell	Table cell of a TableRow containing inline nodes
TableHead	Head part of a Table containing TableRows
TableRow	Table row of a TableHead or TableBody containing TableCells
TablesExt	Extension for GFM tables using "|" pipes.
Text	Text
ThematicBreak	Thematic break block

Alignment
IncludeSourceSpans	Enum for configuring whether to include SourceSpans or not while parsing.

Overview

Fantom library for parsing and rendering Markdown text according to the CommonMark specification.

Usage

using markdown

parser := Parser()
doc := parser.parse("This is *Markdown*")
renderer := HtmlRenderer()
html := renderer.render(doc) // => "<p>This is <em>Markdown</em></p>\n"

This uses the parser and renderer with default options. Both have builders for configuring their behavior. See ParserBuilder and HtmlRendererBuilder for more details.

Use a visitor to process parsed nodes

After the source text has been parsed, the result is a tree of nodes. That tree can be modified before rendering, or just inspected without rendering. See Visitor and the HTML rendering example below.

HTML Rendering

You can take complete control over how HTML is rendered.

In this example, we're changing the rendering of indented code blocks to only wrap them in pre instead of pre and code:

parser := Parser()
renderer := HtmlRenderer.builder
  .nodeRendererFactory(|HtmlContext cx->NodeRenderer| { IndentedCodeBlockRendere(cx) })
  .build
html := renderer.render(parser.parse("Example:\n\n    code"))
// "<p>Example:</p><pre>code</pre>\n"

class IndentedCodeBlockRenderer : NodeRenderer, Visitor
{
  new make(HtmlContext cx) { this.html = cx.writer }
  private HtmlWriter html

  ** We only want to override rendering of the Code node type
  override const Type nodeTypes := [Code#]

  override Void render(Node node) { node.walk(this) }

  override Void visitIndentedCode(IndentedCode code)
  {
    html.line
      .tag("pre")
      .text(code.literal)
      .tag("/pre")
      .line
  }
}

Add your own node types

In case you want to store additional data in the document, or have custom elements in the resulting HTML, you can create your own subclass of CustomNode or CustomBlock and add instances as child nodes to existing nodes.

To define the HTML rendering for them, you can use a NodeRenderer as explained above.

Customize parsing

There are a few ways to extend parsing or even override built-in parsing, all of them via methods on Parser.builder. See Section 3 (Blocks and Inlines) of the spec for an overview of blocks/inlines.

• Parsing of specific block types (e.g. headings, code blocks, etc.) can be enabled/disabled with withEnabledBlockTypes
• Parsing of blocks can be extended/overridden with customBlockParserFactory
• Parsing of inline content can be extended/overridden with customInlineContentParserFactory
• Processing of links can be customized with linkProcessor and linkMarker

Thread-safety

Both the Parser and the HtmlRenderer are designed so that you can configure them once and then use them multiple times/from multiple Actors.

Extensions

Extensions are used to extend the parser, the HTML renderer, or both. Extensions are configured on the various builders using the extensions() method. The default parser and HTML renderer conform to the CommonMark specification. This library includes some built-in extensions that you can optionally enable.

For example, the following code enables the ImgAttrsExt which allows you to specify attributes for images.

using markdown

exts := [ImgAttrsExt()]
parser := Parser.builder.extensions(exts).build
renderer := HtmlRenderer.builder.extensions(exts).build

Image Attributes

Adds support for specifying attributes (specifically height and width) for images. Use ImgAttrsExt to enable this extension.

The attribute elements are given as key=value pairs inside curly braces { } after the image node to which they apply. For example:

![text](/url.png){width=640 height=480}

will be rendered as

<img src="/url.png" alt="text" width="640" height="480" />

Tables

Enables tables using pipes as in Github Flavored Markdown. See TablesExt.

| Header1 | Header2 |
| ------- | ------- |
| foo     | bar     |