Extensions (original) (raw)

Contents

• Configuring Options
• Core
  • Parser
  • Renderer
  • Formatter
• PDF Output Module
• Available Extensions
  • Abbreviation
  • Admonition
  • AnchorLink
  • Aside
  • Attributes
  • Autolink
  • Definition Lists
  • Docx Converter
  • Emoji
  • Enumerated Reference
  • Footnotes
  • Gfm-Issues
  • Gfm-Strikethrough/Subscript
  • Gfm-TaskList
  • Gfm-Users
  • GitLab Flavoured Markdown
  • Html To Markdown
  • Ins
  • Jekyll Tags
  • Jira-Converter
  • Macros
  • Media Tags
  • Resizable Image Extension
  • Spec Example
  • Superscript
  • Tables
  • Table of Contents
  • Typographic
  • WikiLinks
  • XWiki Macro Extension
  • YAML front matter
  • YouTrack-Converter
  • YouTube Embedded Link Transformer

Extensions need to extend the parser, HTML renderer, formatter, or any combination of these. To use an extension, the builder objects can be configured with a list of extensions. Because extensions are optional, they live in separate artifacts, requiring additional dependencies to be added to the project.

Let's look at how to enable tables from GitHub Flavored Markdown or MultiMarkdown, which ever your prefer. First, add all modules as a dependency (see Maven Central for individual modules):

Configure the extension on the builders:

import com.vladsch.flexmark.ext.tables.TablesExtension; import com.vladsch.flexmark.ext.gfm.strikethrough.StrikethroughExtension;

class SomeClass { static final DataHolder OPTIONS = new MutableDataSet() .set(Parser.EXTENSIONS, Arrays.asList(TablesExtension.create(), StrikethroughExtension.create())) .toImmutable();

Parser parser = Parser.builder(options).build();
HtmlRenderer renderer = HtmlRenderer.builder(options).build();

}

Configuring Options

A generic options API allows easy configuration of the parser, renderer and extensions. It consists of DataKey<T> instances defined by various components. Each data key defines the type of its value and a default value.

The values are accessed via the DataHolder and MutableDataHolder interfaces, with the former being a read only container. Since the data key provides a unique identifier for the data there is no collision for options.

To configure the parser or renderer, pass a data holder to the builder() method with the desired options configured, including extensions.

import com.vladsch.flexmark.html.HtmlRenderer; import com.vladsch.flexmark.parser.Parser;

public class SomeClass { static final DataHolder OPTIONS = new MutableDataSet() .set(Parser.REFERENCES_KEEP, KeepType.LAST) .set(HtmlRenderer.INDENT_SIZE, 2) .set(HtmlRenderer.PERCENT_ENCODE_URLS, true)

        // for full GFM table compatibility add the following table extension options:
        .set(TablesExtension.COLUMN_SPANS, false)
        .set(TablesExtension.APPEND_MISSING_COLUMNS, true)
        .set(TablesExtension.DISCARD_EXTRA_COLUMNS, true)
        .set(TablesExtension.HEADER_SEPARATOR_COLUMN_MATCH, true)
        .set(Parser.EXTENSIONS, Arrays.asList(TablesExtension.create()))
        .toImmutable();

static final Parser PARSER = Parser.builder(OPTIONS).build();
static final HtmlRenderer RENDERER = HtmlRenderer.builder(OPTIONS).build();

}

In the code sample above, Parser.REFERENCES_KEEP defines the behavior of references when duplicate references are defined in the source. In this case it is configured to keep the last value, whereas the default behavior is to keep the first value.

The HtmlRenderer.INDENT_SIZE and HtmlRenderer.PERCENT_ENCODE_URLS define options to use for rendering. Similarly, extension options can be added at the same time. Any options not set, will default to their respective defaults as defined by their data keys.

All markdown element reference types should be stored using a subclass of NodeRepository<T> as is the case for references, abbreviations and footnotes. This provides a consistent mechanism for overriding the default behavior of these references for duplicates from keep first to keep last.

By convention, data keys are defined in the extension class and in the case of the core in theParser or HtmlRenderer.

Data keys are described in their respective extension classes and in Parser andHtmlRenderer.

Core

Core implements parser, Html renderer and formatter functionality for CommonMark markdown elements.

Parser

Unified options handling added which are also used to selectively disable loading of core parsers and processors.

Parser.builder() now implements MutableDataHolder so you can use get/set to customize properties directly on it or pass it a DataHolder with predefined options.

Defined in Parser class:

• Parser.ASTERISK_DELIMITER_PROCESSOR : default true enable asterisk delimiter inline processing.
• Parser.BLANK_LINES_IN_AST default false, set to true to include blank line nodes in the AST.
• Parser.BLOCK_QUOTE_ALLOW_LEADING_SPACE : default true, when true leading spaces before > are allowed
• Parser.BLOCK_QUOTE_EXTEND_TO_BLANK_LINE : default false, when true block quotes extend to next blank line. Enables more customary block quote parsing than commonmark strict standard
• Parser.BLOCK_QUOTE_IGNORE_BLANK_LINE : default false, when true block quotes will include blank lines between block quotes and treat them as if the blank lines are also preceded by the block quote marker
• Parser.BLOCK_QUOTE_INTERRUPTS_ITEM_PARAGRAPH : default true, when true block quotes can interrupt list item text, else need blank line before to be included in list items
• Parser.BLOCK_QUOTE_INTERRUPTS_PARAGRAPH : default true, when true block quote can interrupt a paragraph, else needs blank line before
• Parser.BLOCK_QUOTE_PARSER : default true, when true parsing of block quotes is enabled
• Parser.BLOCK_QUOTE_WITH_LEAD_SPACES_INTERRUPTS_ITEM_PARAGRAPH : default true, when true block quotes with leading spaces can interrupt list item text, else need blank line before or no leading spaces
• Parser.CODE_BLOCK_INDENT, default Parser.LISTS_ITEM_INDENT, setting which determines how many leading spaces will treat the following text as an indented block.

ℹ️ In parsers, use state.getParsing().CODE_BLOCK_INDENT to ensure that all parsers have the same setting. Parsing copies the setting from options on creation so having this option changed after parsing phase has started will have no effect.

• Parser.CODE_SOFT_LINE_BREAKS : default false, set to true to include soft line break nodes in code blocks
• Parser.CODE_STYLE_HTML_CLOSE : default (String)null override HTML to use for wrapping style, if null then no override
• Parser.CODE_STYLE_HTML_OPEN : default (String)null override HTML to use for wrapping style, if null then no override
• Parser.EMPHASIS_STYLE_HTML_CLOSE : default (String)null override HTML to use for wrapping style, if null then no override
• Parser.EMPHASIS_STYLE_HTML_OPEN : default (String)null override HTML to use for wrapping style, if null then no override
• Parser.EXTENSIONS : default empty list list of extension to use for builders. Can use this option instead of passing extensions to parser builder and renderer builder.
• Parser.FENCED_CODE_BLOCK_PARSER : default true enable parsing of fenced code blocks
• Parser.FENCED_CODE_CONTENT_BLOCK : default false add CodeBlock as child to contain the code of a fenced block. Otherwise the code is contained in a Text node.
• Parser.HARD_LINE_BREAK_LIMIT : default false only treat the last 2 spaces of a hard line break in the HardLineBreak node if set to true. Otherwise all spaces are used.
• Parser.HEADING_CAN_INTERRUPT_ITEM_PARAGRAPH : default true allow headings to interrupt list item paragraphs
• Parser.HEADING_NO_ATX_SPACE : default false allow headers without a space between # and the header text if true
• Parser.HEADING_NO_EMPTY_HEADING_WITHOUT_SPACE default false, set to true to not recognize empty headings without a space following #
• Parser.HEADING_NO_LEAD_SPACE : default false do not allow non-indent spaces before # for atx headers and text or -/= marker for setext, if true (pegdown and GFM), if false commonmark rules.
• Parser.HEADING_PARSER : default true enable parsing of headings
• Parser.HEADING_SETEXT_MARKER_LENGTH : default 1 sets the minimum number of - or = needed under a setext heading text before it being recognized as a heading.
• Parser.HTML_ALLOW_NAME_SPACE : default false, when true will allow a name space prefix for HTML elements. ❗ HTML Deep Parser always enables name spaces and ignores this option.
• Parser.HTML_BLOCK_COMMENT_ONLY_FULL_LINE : default false, when true will allow embedded HTML comments to interrupt paragraphs.
• Parser.HTML_BLOCK_DEEP_PARSE_BLANK_LINE_INTERRUPTS_PARTIAL_TAG default true, when true blank line interrupts partially open tag ie. <TAG without a corresponding > and having a blank line blank line before >
• Parser.HTML_BLOCK_DEEP_PARSE_BLANK_LINE_INTERRUPTS default true, when true Blank line interrupts HTML block when not in raw tag, otherwise only when closed
• Parser.HTML_BLOCK_DEEP_PARSE_FIRST_OPEN_TAG_ON_ONE_LINE default false, when true do not parse open tags unless they are contained on one line.
• Parser.HTML_BLOCK_DEEP_PARSE_INDENTED_CODE_INTERRUPTS default false, when true Indented code can interrupt HTML block without a preceding blank line.
• Parser.HTML_BLOCK_DEEP_PARSE_MARKDOWN_INTERRUPTS_CLOSED default false, when true Other markdown elements can interrupt a closed HTML block without an intervening blank line
• Parser.HTML_BLOCK_DEEP_PARSE_NON_BLOCK default true, parse non-block tags inside HTML blocks
• Parser.HTML_BLOCK_DEEP_PARSER default false - enable deep HTML block parsing
• Parser.HTML_BLOCK_PARSER : default true enable parsing of html blocks
• Parser.HTML_BLOCK_START_ONLY_ON_BLOCK_TAGS, default for deep html parser is true and regular parser false, but you can set your desired specific value and override the default. When true will not start an HTML block on a non-block tag, when false any tag will start an HTML block.
• Parser.HTML_BLOCK_TAGS, default list: address, article, aside, base, basefont, blockquote, body, caption, center, col, colgroup, dd, details, dialog, dir, div, dl, dt, fieldset, figcaption, figure, footer, form, frame, frameset, h1, h2, h3, h4, h5, h6, head, header, hr, html, iframe, legend, li, link, main, math, menu, menuitem, meta, nav, noframes, ol, optgroup, option, p, param, section, source, summary, table, tbody, td, tfoot, th, thead, title, tr, track, ul, sets the HTML block tags
• Parser.HTML_COMMENT_BLOCKS_INTERRUPT_PARAGRAPH : default true enables HTML comments to interrupt paragraphs, otherwise comment to be interpreted as HTML blocks need a blank line before.
• Parser.HTML_FOR_TRANSLATOR : default false, when true the parser is modified to allow translator placeholders to be recognized
• Parser.INDENTED_CODE_BLOCK_PARSER : default true enable parsing of indented code block
• Parser.INDENTED_CODE_NO_TRAILING_BLANK_LINES : default true enable removing trailing blank lines from indented code blocks
• Parser.INLINE_DELIMITER_DIRECTIONAL_PUNCTUATIONS default false, set to true to use delimiter parsing rules that take bracket open/close into account
• Parser.INTELLIJ_DUMMY_IDENTIFIER : default false add '\u001f' to all parse patterns as an allowable character, used by plugin to allow for IntelliJ completion location marker
• Parser.LINKS_ALLOW_MATCHED_PARENTHESES : default true, when false uses spec 0.27 rules for link addresses and does not resolve matched ()
• Parser.LIST_BLOCK_PARSER : default true enable parsing of lists
• Parser.LIST_REMOVE_EMPTY_ITEMS, default false. If true then empty list items or list items which only contain a BlankLine node are removed from the output.
• Parser.LISTS_END_ON_DOUBLE_BLANK : default false, when true lists are terminated by a double blank line as per spec 0.27 rules.
• Parser.LISTS_ITEM_PREFIX_CHARS : default "*-+", specify which characters mark a list item
• Parser.LISTS_LOOSE_WHEN_CONTAINS_BLANK_LINE : default false, when true a list item which contains a blank line will be considered a loose list item.
• Parser.LISTS_LOOSE_WHEN_LAST_ITEM_PREV_HAS_TRAILING_BLANK_LINE : default false, when true will consider a list with last item followed by blank line as a loose list.
• Parser.MATCH_CLOSING_FENCE_CHARACTERS : default true whether the closing fence character has to match opening character, when false then back ticks can open and tildes close and vice versa. The number of characters in the opener and close still have to be the same.
• Parser.MATCH_NESTED_LINK_REFS_FIRST : default true custom link ref processors that take tested [] have priority over ones that do not. ie. [[^f]][test] is a wiki link with ^f as page ref followed by ref link test when this option is true. IF false then the same would be a ref link test with a footnote ^f refernce for text
• Parser.PARSE_INNER_HTML_COMMENTS : default false when true will parse inner HTML comments in HTML blocks
• Parser.PARSE_JEKYLL_MACROS_IN_URLS default false, set to true to allow any characters to appear between {{ and }} in URLs, including spaces, pipes and backslashes
• Parser.PARSE_MULTI_LINE_IMAGE_URLS : default false allows parsing of multi line urls:
• Parser.PARSER_EMULATION_PROFILE default ParserEmulationProfile.COMMONMARK, set to desired one of the ParserEmulationProfile values
• Parser.REFERENCE_PARAGRAPH_PRE_PROCESSOR : default true enable parsing of reference definitions
• Parser.REFERENCES_KEEP : default KeepType.FIRST which duplicates to keep.
• Parser.REFERENCES : default new repository repository for document's reference definitions
• Parser.SPACE_IN_LINK_ELEMENTS default false, set to true to allow whitespace between ![] or [] and () of links or images.
• Parser.SPACE_IN_LINK_URLS : default false will accept spaces in link address as long as they are not followed by "
• Parser.STRONG_EMPHASIS_STYLE_HTML_CLOSE : default (String)null override HTML to use for wrapping style, if null then no override
• Parser.STRONG_EMPHASIS_STYLE_HTML_OPEN : default (String)null override HTML to use for wrapping style, if null then no override
• Parser.STRONG_WRAPS_EMPHASIS : default false, when true uses spec 0.27 rules for emphasis/strong resolution
• Parser.THEMATIC_BREAK_PARSER : default true enable parsing of thematic breaks
• Parser.THEMATIC_BREAK_RELAXED_START : default true enable parsing of thematic breaks which are not preceded by a blank line
• Parser.TRACK_DOCUMENT_LINES default false. When true document lines are tracked in the document's lineSegments list and offset to line method can be used to get the 0-based line number for the given offset. When false these functions compute the line number by counting EOL sequences before the offset.
• Parser.UNDERSCORE_DELIMITER_PROCESSOR : default true whether to process underscore delimiters
• Parser.USE_HARDCODED_LINK_ADDRESS_PARSER : default true, when false uses regex for link address parsing, which causes StackOverflowError for long URLs
• Parser.WWW_AUTO_LINK_ELEMENT : default false, when true www. prefix is recognized as an auto-link prefix

ℹ️ Parser.USE_HARDCODED_LINK_ADDRESS_PARSER set to true is the default because the regex based parsing requires much more stack space and will causeStackOverflowError error when attempting to parse link URLs larger than about 1.5k characters. This option is available only for backwards compatibility and in case someone customizes the regex for parsing. Performance of the hard-coded parser is on par with the regex one while requiring no stack space for parsing.

List Parsing Options

Because list parsing is the greatest discrepancy between Markdown parser implementations. Before CommonMark there was no hard specification for parsing lists and every implementation took artistic license with how it determines what the list should look like.

flexmark-java implements four parser families based on their list processing characteristics. In addition to ParserEmulationProfile setting, each of the families has a standard set of common options that control list processing, with defaults set by each but modifiable by the end user.

There are a few ways to configure the list parsing options:

1. the recommended way is to apply ParserEmulationProfile to options viaMutableDataHolder.setFrom(ParserEmulationProfile) to have all options configured for a particular parser.
2. start with the ParserEmulationProfile.getOptions() and modify defaults for the family and then pass it to MutableDataHolder.setFrom(MutableDataSetter)
3. by configuring an instance of MutableListOptions and then passing it toMutableDataHolder.setFrom(MutableDataSetter)
4. first via individual keys

List Item Options

• Parser.LISTS_CODE_INDENT : default 4, can be the same as LISTS_ITEM_INDENT or double that for parser emulation families which count indentation from first list item indent
• Parser.LISTS_ITEM_INDENT : default 4, is also the INDENTED CODE INDENT. Parser emulation family either does not use this or expects it to be the number of columns to next indent item (in this case indented code is the same)
• Parser.LISTS_NEW_ITEM_CODE_INDENT : default 4, new item with content indent >= this value causes an empty item with code indent child, weird standard, so far only for CommonMark
• empty list items require explicit space after marker Parser.LISTS_ITEM_MARKER_SPACE, ListOptions.itemMarkerSpace
• mismatch item type starts a new list: Parser.LISTS_ITEM_TYPE_MISMATCH_TO_NEW_LIST, ListOptions.itemTypeMismatchToNewList
• mismatch item type start a sub-list: Parser.LISTS_ITEM_TYPE_MISMATCH_TO_SUB_LIST, ListOptions.itemTypeMismatchToSubList
• bullet or ordered item delimiter mismatch starts a new list: Parser.LISTS_DELIMITER_MISMATCH_TO_NEW_LIST, ListOptions.delimiterMismatchToNewList
• ordered items only with . after digit, otherwise ) is also allowed: Parser.LISTS_ORDERED_ITEM_DOT_ONLY, ListOptions.orderedItemDotOnly
• first ordered item prefix sets start number of list: Parser.LISTS_ORDERED_LIST_MANUAL_START, ListOptions.orderedListManualStart
• item is loose if it contains a blank line after its item text: Parser.LISTS_LOOSE_WHEN_BLANK_LINE_FOLLOWS_ITEM_PARAGRAPH, ListOptions.looseWhenBlankLineFollowsItemParagraph
• item is loose if it is first item and has trailing blank line or if previous item has a trailing blank line: Parser.LISTS_LOOSE_WHEN_PREV_HAS_TRAILING_BLANK_LINE, ListOptions.looseWhenPrevHasTrailingBlankLine
• item is loose if it has loose sub-item: Parser.LISTS_LOOSE_WHEN_HAS_LOOSE_SUB_ITEM, ListOptions.looseWhenHasLooseSubItem
• item is loose if it has trailing blank line in it or its last child: Parser.LISTS_LOOSE_WHEN_HAS_TRAILING_BLANK_LINE, ListOptions.looseWhenHasTrailingBlankLine
• item is loose if it has non-list children: Parser.LISTS_LOOSE_WHEN_HAS_NON_LIST_CHILDREN, ListOptions.looseWhenHasNonListChildren
• all items are loose if any in the list are loose: Parser.LISTS_AUTO_LOOSE, ListOptions.autoLoose
• auto loose list setting Parser.LISTS_AUTO_LOOSE only applies to simple 1 level lists: Parser.LISTS_AUTO_LOOSE_ONE_LEVEL_LISTS, ListOptions.autoLooseOneLevelLists
• list item marker suffixes, content indent computed after suffix: Parser.LISTS_ITEM_MARKER_SUFFIXES, ListOptions.itemMarkerSuffixes
• list item marker suffixes apply to numbered items: Parser.LISTS_NUMBERED_ITEM_MARKER_SUFFIXED, ListOptions.numberedItemMarkerSuffixed
• list item marker suffixes are not used to affect indent offset for child items: Parser.LISTS_ITEM_CONTENT_AFTER_SUFFIX, default false, set to true to treat the item suffix as part of the list item marker after which the content begins for indentation purposes. Gfm Task List uses the default setting.
• Parser.LISTS_AUTO_LOOSE_ONE_LEVEL_LISTS, default false, when true will determine looseness of list item by its content, otherwise will use looseness of contained lists
• Parser.LISTS_LOOSE_WHEN_LAST_ITEM_PREV_HAS_TRAILING_BLANK_LINE, default false, when true a last list item which is preceded by a blank line will be marked as loose item.
• Parser.LISTS_LOOSE_WHEN_CONTAINS_BLANK_LINE, default false, when true an item will be marked as loose if it contains a blank line
• Parser.LISTS_ITEM_PREFIX_CHARS, default "*-+", set to allowed list item prefixes

⚠️ If both LISTS_ITEM_TYPE_MISMATCH_TO_NEW_LIST andLISTS_ITEM_TYPE_MISMATCH_TO_SUB_LIST are set to true then a new list will be created if the item had a blank line, otherwise a sub-list is created.

List Item Paragraph Interruption Options

• bullet item can interrupt a paragraph: Parser.LISTS_BULLET_ITEM_INTERRUPTS_PARAGRAPH, ListOptions.itemInterrupt.bulletItemInterruptsParagraph
• ordered item can interrupt a paragraph: Parser.LISTS_ORDERED_ITEM_INTERRUPTS_PARAGRAPH, ListOptions.itemInterrupt.orderedItemInterruptsParagraph
• ordered non 1 item can interrupt a paragraph: Parser.LISTS_ORDERED_NON_ONE_ITEM_INTERRUPTS_PARAGRAPH, ListOptions.itemInterrupt.orderedNonOneItemInterruptsParagraph
• empty bullet item can interrupt a paragraph: Parser.LISTS_EMPTY_BULLET_ITEM_INTERRUPTS_PARAGRAPH, ListOptions.itemInterrupt.emptyBulletItemInterruptsParagraph
• empty ordered item can interrupt a paragraph: Parser.LISTS_EMPTY_ORDERED_ITEM_INTERRUPTS_PARAGRAPH, ListOptions.itemInterrupt.emptyOrderedItemInterruptsParagraph
• empty ordered non 1 item can interrupt a paragraph: Parser.LISTS_EMPTY_ORDERED_NON_ONE_ITEM_INTERRUPTS_PARAGRAPH, ListOptions.itemInterrupt.emptyOrderedNonOneItemInterruptsParagraph
• bullet item can interrupt a paragraph of a list item: Parser.LISTS_BULLET_ITEM_INTERRUPTS_ITEM_PARAGRAPH, ListOptions.itemInterrupt.bulletItemInterruptsItemParagraph
• ordered item can interrupt a paragraph of a list item: Parser.LISTS_ORDERED_ITEM_INTERRUPTS_ITEM_PARAGRAPH, ListOptions.itemInterrupt.orderedItemInterruptsItemParagraph
• ordered non 1 item can interrupt a paragraph of a list item: Parser.LISTS_ORDERED_NON_ONE_ITEM_INTERRUPTS_ITEM_PARAGRAPH, ListOptions.itemInterrupt.orderedNonOneItemInterruptsItemParagraph
• empty bullet item can interrupt a paragraph of a list item: Parser.LISTS_EMPTY_BULLET_ITEM_INTERRUPTS_ITEM_PARAGRAPH, ListOptions.itemInterrupt.emptyBulletItemInterruptsItemParagraph
• empty ordered non 1 item can interrupt a paragraph of a list item: Parser.LISTS_EMPTY_ORDERED_ITEM_INTERRUPTS_ITEM_PARAGRAPH, ListOptions.itemInterrupt.emptyOrderedItemInterruptsItemParagraph
• empty ordered item can interrupt a paragraph of a list item: Parser.LISTS_EMPTY_ORDERED_NON_ONE_ITEM_INTERRUPTS_ITEM_PARAGRAPH, ListOptions.itemInterrupt.emptyOrderedNonOneItemInterruptsItemParagraph
• empty bullet sub-item can interrupt a paragraph of a list item: Parser.LISTS_EMPTY_BULLET_SUB_ITEM_INTERRUPTS_ITEM_PARAGRAPH, ListOptions.itemInterrupt.emptyBulletSubItemInterruptsItemParagraph
• empty ordered non 1 sub-item can interrupt a paragraph of a list item: Parser.LISTS_EMPTY_ORDERED_SUB_ITEM_INTERRUPTS_ITEM_PARAGRAPH, ListOptions.itemInterrupt.emptyOrderedSubItemInterruptsItemParagraph
• empty ordered sub-item can interrupt a paragraph of a list item: Parser.LISTS_EMPTY_ORDERED_NON_ONE_SUB_ITEM_INTERRUPTS_ITEM_PARAGRAPH, ListOptions.itemInterrupt.emptyOrderedNonOneSubItemInterruptsItemParagraph

Renderer

Unified options handling added, existing configuration options were kept but now they modify the corresponding unified option.

Renderer Builder() now has an indentSize(int) method to set size of indentation for hierarchical tags. Same as setting HtmlRenderer.INDENT_SIZE data key in options.

Defined in HtmlRenderer class:

• AUTOLINK_WWW_PREFIX : default "http://" prefix to add to autolink if it starts with www.
• CODE_STYLE_HTML_CLOSE default ``(String) null, custom inline code close HTML
• CODE_STYLE_HTML_OPEN default (String) null, custom inline code open HTML
• DO_NOT_RENDER_LINKS default false, Disable link rendering in the document. This will cause sub-contexts to also have link rendering disabled.
• EMPHASIS_STYLE_HTML_CLOSE default (String) null, custom emphasis close HTML
• EMPHASIS_STYLE_HTML_OPEN default (String) null, custom emphasis open HTML
• ESCAPE_HTML_BLOCKS default value of ESCAPE_HTML, escape html blocks found in the document
• ESCAPE_HTML_COMMENT_BLOCKS default value of ESCAPE_HTML_BLOCKS, escape html comment blocks found in the document.
• ESCAPE_HTML default false, escape all html found in the document
• ESCAPE_INLINE_HTML_COMMENTS default value of ESCAPE_HTML_BLOCKS, escape inline html found in the document
• ESCAPE_INLINE_HTML default value of ESCAPE_HTML, escape inline html found in the document
• FENCED_CODE_LANGUAGE_CLASS_MAP, default new HashMap(), provides individual language to class mapping string. If language string is not in the map then FENCED_CODE_LANGUAGE_CLASS_PREFIX + language will be used.
• FENCED_CODE_LANGUAGE_CLASS_PREFIX default "language-", prefix used for generating the <code> class for a fenced code block, only used if info is not empty and language is not defined in FENCED_CODE_LANGUAGE_CLASS_MAP
• FENCED_CODE_NO_LANGUAGE_CLASS default "" ,<code> class for <code> tag of indented code or fenced code block without info (language) specification
• FORMAT_FLAGS default 0, Flags used for FormattingAppendable used for rendering HTML
• GENERATE_HEADER_ID default false, Generate a header id attribute using the configured HtmlIdGenerator but not render it. The id may be used by another element such as an anchor link.
• HARD_BREAK default "<br />\n", string to use for rendering hard breaks
• HEADER_ID_ADD_EMOJI_SHORTCUT, default false. When set to true, emoji shortcut nodes add the shortcut to collected text used to generate heading id.
• HEADER_ID_GENERATOR_NO_DUPED_DASHES default false, When true duplicate - in id will be replaced by a single -
• HEADER_ID_GENERATOR_NON_ASCII_TO_LOWERCASE, default true. When set to false changes the default header id generator to not convert non-ascii alphabetic characters to lowercase. Needed for GitHub id compatibility.
• HEADER_ID_GENERATOR_RESOLVE_DUPES default true, When true will add an incrementing integer to duplicate ids to make them unique
• HEADER_ID_GENERATOR_TO_DASH_CHARS default "_", set of characters to convert to - in text used to generate id, non-alpha numeric chars not in set will be removed
• HEADER_ID_REF_TEXT_TRIM_LEADING_SPACES, default true. When set to false then leading spaces in link reference text in heading is not trimmed for text used to generate id.
• HEADER_ID_REF_TEXT_TRIM_TRAILING_SPACES, default true. When set to false then trailing spaces in link reference text in heading is not trimmed for text used to generate id.
• HTML_BLOCK_CLOSE_TAG_EOL default true, When false will suppress EOL after HTML block tags which are automatically generated during html rendering.
• HTML_BLOCK_OPEN_TAG_EOL default true, When false will suppress EOL before HTML block tags which are automatically generated during html rendering.
• INDENT_SIZE default 0, how many spaces to use for each indent level of nested tags
• INLINE_CODE_SPLICE_CLASS default (String) null, used for splitting and splicing inline code spans for source line tracking
• MAX_TRAILING_BLANK_LINES default 1, Maximum allowed trailing blank lines for rendered HTML
• OBFUSCATE_EMAIL_RANDOM default true, When false will not use random number generator for obfuscation. Used for tests
• OBFUSCATE_EMAIL default false, When true will obfuscate mailto links
• PERCENT_ENCODE_URLS default false, percent encode urls
• RECHECK_UNDEFINED_REFERENCES default false, Recheck the existence of refences in Parser.REFERENCES for link and image refs marked undefined. Used when new references are added after parsing
• RENDER_HEADER_ID default false, Render a header id attribute for headers using the configured HtmlIdGenerator
• SOFT_BREAK default "\n", string to use for rendering soft breaks
• SOURCE_POSITION_ATTRIBUTE default "", name of the source position HTML attribute, source position is assigned as startOffset + '-' + endOffset
• SOURCE_POSITION_PARAGRAPH_LINES default false, if true enables wrapping individual paragraph source lines in span with source position attribute set
• SOURCE_WRAP_HTML_BLOCKS default value of SOURCE_WRAP_HTML, if generating source position attribute, then wrap HTML blocks in div with source position
• SOURCE_WRAP_HTML default false, if generating source position attribute, then wrap HTML with source position
• STRONG_EMPHASIS_STYLE_HTML_CLOSE default (String) null, custom strong emphasis close HTML
• STRONG_EMPHASIS_STYLE_HTML_OPEN default (String) null, custom strong emphasis open HTML
• SUPPRESS_HTML_BLOCKS default value of SUPPRESS_HTML, suppress html output for html blocks
• SUPPRESS_HTML_COMMENT_BLOCKS default value of SUPPRESS_HTML_BLOCKS, suppress html output for html comment blocks
• SUPPRESS_HTML default false, suppress html output for all html
• SUPPRESS_INLINE_HTML_COMMENTS default value of SUPPRESS_INLINE_HTML, suppress html output for inline html comments
• SUPPRESS_INLINE_HTML default value of SUPPRESS_HTML, suppress html output for inline html
• SUPPRESS_LINKS default value of "javascript:.*", a regular expression to suppress any links that match. The test occurs before the link is resolved using a link resolver. Therefore any link matching will be suppressed before it is resolved. Likewise, a link resolver returning a suppressed link will not be suppressed since this is up to the custom link resolver to handle.

Suppressed links will render only the child nodes, effectively [Something New](javascript:alert(1)) will render as if it was Something New.

Link suppression based on URL prefixes does not apply to HTML inline or block elements. Use HTML suppression options for this.

• TYPE default "HTML", renderer type. Renderer type extensions can add their own. JiraConverterExtension defines JIRA
• UNESCAPE_HTML_ENTITIES default true, When false will leave HTML entities as is in the rendered HTML.

❗ All the escape and suppress options have dynamic default value. This allows you to set the ESCAPE_HTML and have all html escaped. If you set a value of a specific key then the set value will be used for that key. Similarly, comment affecting keys take their values from the non-comment counterpart. If you want to exclude comments from being affected by suppression or escaping then you need to set the corresponding comment key to false and set the non-comment key to true.

Formatter

Formatter renders the AST as markdown with various formatting options to clean up and make the source consistent and possibly convert from one indentation rule set to another. Formatter API allows extensions to provide and handle formatting options for custom nodes.

ℹ️ in versions prior to 0.60.0 formatter functionality was implemented inflexmark-formatter module and required an additional dependency.

See: Markdown Formatter

Formatter can also be used to help translate the markdown document to another language by extracting translatable strings, replacing non-translatable strings with an identifier and finally replacing the translatable text spans with translated versions.

See: Translation Helper API

Formatter can be used to merge multiple markdown documents into a single document while preserving reference resolution to references within each document, even when reference ids conflict between merged documents.

See: Markdown Merge API

PDF Output Module

HTML to PDF conversion is done using Open HTML To PDF library by PdfConverterExtension inflexmark-pdf-converter module.

See: PDF Renderer Converter

Usage PDF Output

Available Extensions

The following extensions are developed with this library, each in their own artifact.

Extension options are defined in their extension class.

Abbreviation

Allows to create abbreviations which will be replaced in plain text into <abbr></abbr> tags or optionally into <a></a> with titles for the abbreviation expansion.

Use class AbbreviationExtension from artifact flexmark-ext-abbreviation.

The following options are available:

Defined in AbbreviationExtension class:

Admonition

To create block-styled side content. Based on Admonition Extension, Material for MkDocs(Personal opinion: Material for MkDocs is eye-candy. If you have not taken a look at it, you are missing out on a visual treat.). See Admonition Extension

Use class AbbreviationExtension from artifact flexmark-ext-admonition.

CSS and JavaScript must be included in your page

Default CSS and JavaScript are contained in the jar as resources:

• admonition.css
• admonition.js

Their content is also available by calling AdmonitionExtension.getDefaultCSS() andAdmonitionExtension.getDefaultScript() static methods.

The script should be included at the bottom of the body of the document and is used to toggle open/closed state of collapsible admonition elements.

AnchorLink

Automatically adds anchor links to heading, using GitHub id generation algorithm

⚠️ This extension will only render an anchor link for headers that have an id attribute associated with them. You need to have the HtmlRenderer.GENERATE_HEADER_ID option to set totrue so that header ids are generated.

Use class AnchorLinkExtension from artifact flexmark-ext-anchorlink.

The following options are available:

Defined in AnchorLinkExtension class:

Aside

Same as block quotes but uses | for prefix and generates <aside> tags. To make it compatible with the table extension, aside block lines cannot have | as the last character of the line, and if using this extension the tables must have the lines terminate with a | otherwise they will be treated as aside blocks.

Use class AsideExtension from artifact flexmark-ext-aside.

Defined in AsideExtension class:

AsideExtension option keys are dynamic data keys dependent on corresponding Parser block quote options for their defaults. If they are not explicitly set then they will take their default value from the value of the corresponding block quote value (prefix BLOCK_QUOTE_ toAsideExtension key name to get Parser block quote key name).

⚠️ This can potentially break code relying on versions of the extension before 0.40.20because parsing rules can change depending on which block quote options are changed from their default values.

To ensure independent options for aside blocks and block quotes, set aside options explicitly. The following will set all aside options to default values, independent from block quote options:

.set(EXTEND_TO_BLANK_LINE, false)
.set(IGNORE_BLANK_LINE, false)
.set(ALLOW_LEADING_SPACE, true)
.set(INTERRUPTS_PARAGRAPH, true)
.set(INTERRUPTS_ITEM_PARAGRAPH, true)
.set(WITH_LEAD_SPACES_INTERRUPTS_ITEM_PARAGRAPH, true)

Attributes

Converts attributes {...} syntax into attributes AST nodes and adds an attribute provider to set attributes for immediately preceding sibling element during HTML rendering. SeeAttributes Extension

Defined in AttributeExtension from artifact flexmark-ext-attributes

• ASSIGN_TEXT_ATTRIBUTES, default true. When false attribute assignment rules to nodes are changed not to allow text elements to get attributes.
• FENCED_CODE_INFO_ATTRIBUTES, default true. When false attribute assignment at end of fenced code info string will be ignored.
• USE_EMPTY_IMPLICIT_AS_SPAN_DELIMITER, default false. When set to true will treat {#}or {.}, without embedded spaced, as start attribute span delimiter to mark start of attribute assignment to text between {.} or {#} and the matching attributes element.

Use class AttributesExtension from artifact flexmark-ext-attributes.

Full spec:ext_attributes_ast_spec

Autolink

Turns plain links such as URLs and email addresses into links (based on autolink-java).

⚠️ current implementation has significant performance impact on large files.

Use class AutolinkExtension from artifact flexmark-ext-autolink.

Defined in AsideExtension class:

• IGNORE_LINKS , default "", a regex expression to match link text which should not be auto-linked. This can include full urls like www.google.com or parts by including wildcard match patterns. Any recognized auto-link which matches the expression will be rendered as text.

Definition Lists

Converts definition syntax of Php Markdown Extra Definition List to <dl></dl> HTML and corresponding AST nodes.

Definition items can be preceded by : or ~, depending on the configured options.

Use class DefinitionExtension from artifact flexmark-ext-definition.

The following options are available:

Defined in DefinitionExtension class:

ℹ️ this extension uses list parsing and indentation rules and will its best to align list item and definition item parsing according to selected options. For non-fixed indent family of parsers will use the definition item content indent column for sub-items, otherwise uses the Parser.LISTS_ITEM_INDENT value for sub-items.

Wiki: Definition List Extension

Docx Converter

Renders the parsed Markdown AST to docx format using the docx4j library.

artifact: flexmark-docx-converter

See the DocxConverterCommonMark Sample for code and Customizing Docx Rendering for an overview and information on customizing the styles.

Pegdown version can be found in DocxConverterPegdown Sample

For details see Docx Renderer Extension

Emoji

Allows to create image link to emoji images from emoji shortcuts using Emoji-Cheat-Sheet.com,GitHub Emoji API and optionally to replace with its unicode equivalent character with mapping to GitHub shortcut or Emoji-Cheat-Sheet.com shortcut based on the file name.

Use class EmojiExtension from artifact flexmark-ext-emoji.

The following options are available:

Defined in EmojiExtension class:

• ATTR_ALIGN, default "absmiddle", attributes to use for rendering in the absence of attribute provider overrides
• ATTR_IMAGE_SIZE, default "20" , attributes to use for rendering in the absence of attribute provider overrides
• ATTR_IMAGE_CLASS, default "", if not empty will set the image tag class attribute to this value.
• ROOT_IMAGE_PATH, default "/img/" , root path for emoji image files. SeeEmoji-Cheat-Sheet.com GitHub Repository repository for image files located inpublic/graphics/emojis directory.
• USE_UNICODE_FILE_NAMES, default false. When true will use unicodeSampleFile field forEmoji Cheat Sheet image file name, if available. This is to support implementations which rely on the file renaming done by emoji-cross-reference when copying emoji cheat sheet images to common emoji_images/emojis directory.
• USE_SHORTCUT_TYPE, default EmojiShortcutType.EMOJI_CHEAT_SHEET, select type of shortcuts:
  • EmojiShortcutType.EMOJI_CHEAT_SHEET
  • EmojiShortcutType.GITHUB
  • EmojiShortcutType.ANY_EMOJI_CHEAT_SHEET_PREFERRED use any shortcut from any source. If image type options is not UNICODE_ONLY, will generate links to Emoji Cheat Sheet files or GitHub URL, with preference given to Emoji Cheat Sheet files.
  • EmojiShortcutType.ANY_GITHUB_PREFERRED - use any shortcut from any source. If image type options is not UNICODE_ONLY, will generate links to Emoji Cheat Sheet files or GitHub URL, with preference given to GitHub URL.
• USE_IMAGE_TYPE, default EmojiImageType.IMAGE_ONLY, to select what type of images are allowed.
  • EmojiImageType.IMAGE_ONLY, only use image link
  • EmojiImageType.UNICODE_ONLY convert to unicode and if there is no unicode treat as invalid emoji shortcut
  • EmojiImageType.UNICODE_FALLBACK_TO_IMAGE convert to unicode and if no unicode use image. emoji shortcuts using Emoji-Cheat-Sheet.com https://www.webfx.com/tools/emoji-cheat-sheet

Enumerated Reference

Used to create numbered references and numbered text labels for elements in the document.Enumerated References Extension

Use class EnumeratedReferenceExtension from artifact flexmark-ext-enumerated-reference.

❗ Note Attributes extension is needed in order for references to be properly resolved for rendering.

Footnotes

Creates footnote references in the document. Footnotes are placed at the bottom of the rendered document with links from footnote references to footnote and vice-versa. Footnotes Extension

Converts: [^footnote] to footnote references and [^footnote]: footnote definition to footnotes in the document.

Gfm-Issues

Enables Gfm issue reference parsing in the form of #123

Use class GfmIssuesExtension in artifact flexmark-ext-gfm-issues.

The following options are available:

Defined in GfmIssuesExtension class:

• GIT_HUB_ISSUES_URL_ROOT : default "issues" override root used for generating the URL
• GIT_HUB_ISSUE_URL_PREFIX : default "/" override prefix used for appending the issue number to URL
• GIT_HUB_ISSUE_URL_SUFFIX : default "" override suffix used for appending the issue number to URL
• GIT_HUB_ISSUE_HTML_PREFIX : default "" override HTML to use as prefix for the issue text
• GIT_HUB_ISSUE_HTML_SUFFIX : default "" override HTML to use as suffix for the issue text

Gfm-Strikethrough/Subscript

Enables strikethrough of text by enclosing it in ~~. For example, in hey ~~you~~, you will be rendered as strikethrough text.

Use class StrikethroughExtension in artifact flexmark-ext-gfm-strikethrough.

Enables subscript of text by enclosing it in ~. For example, in hey ~you~, you will be rendered as subscript text.

Use class SubscriptExtension in artifact flexmark-ext-gfm-strikethrough.

To enables both subscript and strike through:

Use class StrikethroughSubscriptExtension in artifact flexmark-ext-gfm-strikethrough.

⚠️ Only one of these extensions can be included in the extension list. If you want both strikethrough and subscript use the StrikethroughSubscriptExtension.

The following options are available:

Defined in StrikethroughSubscriptExtension class:

• STRIKETHROUGH_STYLE_HTML_OPEN : default (String)null override HTML to use for wrapping style, if null then no override
• STRIKETHROUGH_STYLE_HTML_CLOSE : default (String)null override HTML to use for wrapping style, if null then no override
• SUBSCRIPT_STYLE_HTML_OPEN : default (String)null override HTML to use for wrapping style, if null then no override
• SUBSCRIPT_STYLE_HTML_CLOSE : default (String)null override HTML to use for wrapping style, if null then no override

Gfm-TaskList

Enables list items based task lists whose text begins with: [ ], [x] or [X]

Use class TaskListExtension in artifact flexmark-ext-gfm-tasklist.

The following options are available:

Defined in TaskListExtension class:

• TaskListItemCase
  • AS_IS: no change
  • LOWERCASE: change [X] to [x]
  • UPPERCASE: change [x] to [X]
• TaskListItemPlacement
  • AS_IS: no change
  • INCOMPLETE_FIRST: sort all lists to put incomplete task items first
  • INCOMPLETE_NESTED_FIRST: sort all lists to put incomplete task items or items with incomplete task sub-items first
  • COMPLETE_TO_NON_TASK: sort all lists to put incomplete task items first and change complete task items to non-task items
  • COMPLETE_NESTED_TO_NON_TASK: sort all lists to put incomplete task items or items with incomplete task sub-items first and change complete task items to non-task items

Gfm-Users

Enables Gfm user reference parsing in the form of #123

Use class GfmUsersExtension in artifact flexmark-ext-gfm-users.

The following options are available:

Defined in GfmUsersExtension class:

• GIT_HUB_USERS_URL_ROOT : default "https://github.com" override root used for generating the URL
• GIT_HUB_USER_URL_PREFIX : default "/" override prefix used for appending the user name to URL
• GIT_HUB_USER_URL_SUFFIX : default "" override suffix used for appending the user name to URL
• GIT_HUB_USER_HTML_PREFIX : default "<strong>" override HTML to use as prefix for the user name text
• GIT_HUB_USER_HTML_SUFFIX : default "</strong>" override HTML to use as suffix for the user name text

GitLab Flavoured Markdown

Parses and rendersGitLab Flavoured Markdown.

• Add: video link renderer to convert links to video files to embedded content. The valid video extensions are .mp4, .m4v, .mov, .webm, and .ogv.

<div class="video-container">  
<video src="video.mp4" width="400" controls="true"></video>  
<p><a href="video.mp4" target="_blank" rel="noopener noreferrer" title="Download 'Sample Video'">Sample Video</a></p>  
</div>  

• Multiline Block quote delimiters >>>
• Deleted text markers {- -} or [- -]
• Inserted text markers {+ +} or [+ +]
• Math, inline via <span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi mathvariant="normal">‘</mi><mi mathvariant="normal">‘</mi></mrow><annotation encoding="application/x-tex">``</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.6944em;"></span><span class="mord">‘‘</span></span></span></span> or as fenced code with math info string requiring inclusion of Katex in the rendered HTML page.
• Graphing via Mermaid as fenced code with mermaid info string, via Mermaid inclusion similar to Math solution above.

Use class GitLabExtension in artifact flexmark-ext-gitlab.

The following options are available:

Defined in GitLabExtension class:

• INS_PARSER : default true, enable ins parser
• DEL_PARSER : default true, enable del parser
• BLOCK_QUOTE_PARSER : default true, enable multi-line block quote parser
• INLINE_MATH_PARSER : default true, enable inline math parser
• RENDER_BLOCK_MATH : default true, enable rendering math fenced code blocks as math elements
• RENDER_BLOCK_MERMAID : default true, enable rendering mermaid fenced code blocks as mermaid elements
• RENDER_VIDEO_IMAGES : default true, enable rendering image links with video extensions as video elements
• RENDER_VIDEO_LINK : default true, enable rendering video link with video images
• INLINE_MATH_CLASS : default "katex", inline math class attribute
• BLOCK_MATH_CLASS : default "katex" block math class attribute
• BLOCK_MERMAID_CLASS : default "mermaid" block mermaid class attribute
• VIDEO_IMAGE_CLASS : default "video-container" class attribute
• VIDEO_IMAGE_LINK_TEXT_FORMAT : default "Download '%s'" format for video link text, %s replaced with image alt text
• BLOCK_INFO_DELIMITERS : default " ", delimiters used for extracting math and mermaid strings from fenced code info string
• VIDEO_IMAGE_EXTENSIONS : default "mp4,m4v,mov,webm,ogv", extensions of video files which to render as video

ℹ️ to have Math and Mermaid properly rendered requires inclusion ofKatex and Mermaid scripts in the HTML page.

If you have the files in the same directory as the HTML page, somewhere between the <head> and</head> tags, you need to include:

In addition to the Katex script you need to add JavaScript to the bottom of the page body to convert math elements when the DOM is loaded: