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):
<dependency> <groupId>com.vladsch.flexmark</groupId> <artifactId>flexmark-all</artifactId> <version>0.64.8</version> </dependency>
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(); }
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 the Parser
or HtmlRenderer
.
Data keys are described in their respective extension classes and in Parser
and HtmlRenderer
.
Core implements parser, Html renderer and formatter functionality for CommonMark markdown elements.
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 allowedParser.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 standardParser.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 markerParser.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 itemsParser.BLOCK_QUOTE_INTERRUPTS_PARAGRAPH
: default true
, when true
block quote can interrupt a paragraph, else needs blank line beforeParser.BLOCK_QUOTE_PARSER
: default true
, when true
parsing of block quotes is enabledParser.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 spacesParser.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 cause StackOverflowError
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.
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:
ParserEmulationProfile
to options via MutableDataHolder.setFrom(ParserEmulationProfile)
to have all options configured for a particular parser.ParserEmulationProfile.getOptions()
and modify defaults for the family and then pass it to MutableDataHolder.setFrom(MutableDataSetter)
MutableListOptions
and then passing it to MutableDataHolder.setFrom(MutableDataSetter)
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 indentParser.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 CommonMarkParser.LISTS_ITEM_MARKER_SPACE
, ListOptions.itemMarkerSpace
Parser.LISTS_ITEM_TYPE_MISMATCH_TO_NEW_LIST
, ListOptions.itemTypeMismatchToNewList
Parser.LISTS_ITEM_TYPE_MISMATCH_TO_SUB_LIST
, ListOptions.itemTypeMismatchToSubList
Parser.LISTS_DELIMITER_MISMATCH_TO_NEW_LIST
, ListOptions.delimiterMismatchToNewList
.
after digit, otherwise )
is also allowed: Parser.LISTS_ORDERED_ITEM_DOT_ONLY
, ListOptions.orderedItemDotOnly
Parser.LISTS_ORDERED_LIST_MANUAL_START
, ListOptions.orderedListManualStart
Parser.LISTS_LOOSE_WHEN_BLANK_LINE_FOLLOWS_ITEM_PARAGRAPH
, ListOptions.looseWhenBlankLineFollowsItemParagraph
Parser.LISTS_LOOSE_WHEN_PREV_HAS_TRAILING_BLANK_LINE
, ListOptions.looseWhenPrevHasTrailingBlankLine
Parser.LISTS_LOOSE_WHEN_HAS_LOOSE_SUB_ITEM
, ListOptions.looseWhenHasLooseSubItem
Parser.LISTS_LOOSE_WHEN_HAS_TRAILING_BLANK_LINE
, ListOptions.looseWhenHasTrailingBlankLine
Parser.LISTS_LOOSE_WHEN_HAS_NON_LIST_CHILDREN
, ListOptions.looseWhenHasNonListChildren
Parser.LISTS_AUTO_LOOSE
, ListOptions.autoLoose
Parser.LISTS_AUTO_LOOSE
only applies to simple 1 level lists: Parser.LISTS_AUTO_LOOSE_ONE_LEVEL_LISTS
, ListOptions.autoLooseOneLevelLists
Parser.LISTS_ITEM_MARKER_SUFFIXES
, ListOptions.itemMarkerSuffixes
Parser.LISTS_NUMBERED_ITEM_MARKER_SUFFIXED
, ListOptions.numberedItemMarkerSuffixed
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 listsParser.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 lineParser.LISTS_ITEM_PREFIX_CHARS
, default "*-+"
, set to allowed list item prefixes⚠️ If both LISTS_ITEM_TYPE_MISMATCH_TO_NEW_LIST
and LISTS_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.
Parser.LISTS_BULLET_ITEM_INTERRUPTS_PARAGRAPH
, ListOptions.itemInterrupt.bulletItemInterruptsParagraph
Parser.LISTS_ORDERED_ITEM_INTERRUPTS_PARAGRAPH
, ListOptions.itemInterrupt.orderedItemInterruptsParagraph
Parser.LISTS_ORDERED_NON_ONE_ITEM_INTERRUPTS_PARAGRAPH
, ListOptions.itemInterrupt.orderedNonOneItemInterruptsParagraph
Parser.LISTS_EMPTY_BULLET_ITEM_INTERRUPTS_PARAGRAPH
, ListOptions.itemInterrupt.emptyBulletItemInterruptsParagraph
Parser.LISTS_EMPTY_ORDERED_ITEM_INTERRUPTS_PARAGRAPH
, ListOptions.itemInterrupt.emptyOrderedItemInterruptsParagraph
Parser.LISTS_EMPTY_ORDERED_NON_ONE_ITEM_INTERRUPTS_PARAGRAPH
, ListOptions.itemInterrupt.emptyOrderedNonOneItemInterruptsParagraph
Parser.LISTS_BULLET_ITEM_INTERRUPTS_ITEM_PARAGRAPH
, ListOptions.itemInterrupt.bulletItemInterruptsItemParagraph
Parser.LISTS_ORDERED_ITEM_INTERRUPTS_ITEM_PARAGRAPH
, ListOptions.itemInterrupt.orderedItemInterruptsItemParagraph
Parser.LISTS_ORDERED_NON_ONE_ITEM_INTERRUPTS_ITEM_PARAGRAPH
, ListOptions.itemInterrupt.orderedNonOneItemInterruptsItemParagraph
Parser.LISTS_EMPTY_BULLET_ITEM_INTERRUPTS_ITEM_PARAGRAPH
, ListOptions.itemInterrupt.emptyBulletItemInterruptsItemParagraph
Parser.LISTS_EMPTY_ORDERED_ITEM_INTERRUPTS_ITEM_PARAGRAPH
, ListOptions.itemInterrupt.emptyOrderedItemInterruptsItemParagraph
Parser.LISTS_EMPTY_ORDERED_NON_ONE_ITEM_INTERRUPTS_ITEM_PARAGRAPH
, ListOptions.itemInterrupt.emptyOrderedNonOneItemInterruptsItemParagraph
Parser.LISTS_EMPTY_BULLET_SUB_ITEM_INTERRUPTS_ITEM_PARAGRAPH
, ListOptions.itemInterrupt.emptyBulletSubItemInterruptsItemParagraph
Parser.LISTS_EMPTY_ORDERED_SUB_ITEM_INTERRUPTS_ITEM_PARAGRAPH
, ListOptions.itemInterrupt.emptyOrderedSubItemInterruptsItemParagraph
Parser.LISTS_EMPTY_ORDERED_NON_ONE_SUB_ITEM_INTERRUPTS_ITEM_PARAGRAPH
, ListOptions.itemInterrupt.emptyOrderedNonOneSubItemInterruptsItemParagraph
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 HTMLCODE_STYLE_HTML_OPEN
default (String) null
, custom inline code open HTMLDO_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 HTMLEMPHASIS_STYLE_HTML_OPEN
default (String) null
, custom emphasis open HTMLESCAPE_HTML_BLOCKS
default value of ESCAPE_HTML
, escape html blocks found in the documentESCAPE_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 documentESCAPE_INLINE_HTML_COMMENTS
default value of ESCAPE_HTML_BLOCKS
, escape inline html found in the documentESCAPE_INLINE_HTML
default value of ESCAPE_HTML
, escape inline html found in the documentFENCED_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) specificationFORMAT_FLAGS
default 0
, Flags used for FormattingAppendable
used for rendering HTMLGENERATE_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 breaksHEADER_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 uniqueHEADER_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 removedHEADER_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 tagsINLINE_CODE_SPLICE_CLASS
default (String) null
, used for splitting and splicing inline code spans for source line trackingMAX_TRAILING_BLANK_LINES
default 1
, Maximum allowed trailing blank lines for rendered HTMLOBFUSCATE_EMAIL_RANDOM
default true
, When false
will not use random number generator for obfuscation. Used for testsOBFUSCATE_EMAIL
default false
, When true
will obfuscate mailto
linksPERCENT_ENCODE_URLS
default false
, percent encode urlsRECHECK_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 parsingRENDER_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 breaksSOURCE_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 setSOURCE_WRAP_HTML_BLOCKS
default value of SOURCE_WRAP_HTML, if generating source position attribute, then wrap HTML blocks in div
with source positionSOURCE_WRAP_HTML
default false
, if generating source position attribute, then wrap HTML with source positionSTRONG_EMPHASIS_STYLE_HTML_CLOSE
default (String) null
, custom strong emphasis close HTMLSTRONG_EMPHASIS_STYLE_HTML_OPEN
default (String) null
, custom strong emphasis open HTMLSUPPRESS_HTML_BLOCKS
default value of SUPPRESS_HTML
, suppress html output for html blocksSUPPRESS_HTML_COMMENT_BLOCKS
default value of SUPPRESS_HTML_BLOCKS
, suppress html output for html comment blocksSUPPRESS_HTML
default false
, suppress html output for all htmlSUPPRESS_INLINE_HTML_COMMENTS
default value of SUPPRESS_INLINE_HTML
, suppress html output for inline html commentsSUPPRESS_INLINE_HTML
default value of SUPPRESS_HTML
, suppress html output for inline htmlSUPPRESS_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 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 in flexmark-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.
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
HTML to PDF conversion is done using Open HTML To PDF library by PdfConverterExtension
in flexmark-pdf-converter
module.
The following extensions are developed with this library, each in their own artifact.
Extension options are defined in their extension class.
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:
ABBREVIATIONS
new repository repository for document's abbreviation definitions ABBREVIATIONS_KEEP
KeepType.FIRST
which duplicates to keep. USE_LINKS
false
use <a>
instead of <abb>
tags for rendering html ABBREVIATIONS_PLACEMENT
ElementPlacement.AS_IS
formatting option see: Markdown Formatter ABBREVIATIONS_SORT
ElementPlacement.AS_IS
formatting option see: Markdown Formatter
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
.
Default CSS and JavaScript are contained in the jar as resources:
Their content is also available by calling AdmonitionExtension.getDefaultCSS()
and AdmonitionExtension.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.
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 to true
so that header ids are generated.
Use class AnchorLinkExtension
from artifact flexmark-ext-anchorlink
.
The following options are available:
Defined in AnchorLinkExtension
class:
ANCHORLINKS_SET_ID
true
whether to set the id attribute to the header id, if true ANCHORLINKS_SET_NAME
false
whether to set the name attribute to the header id, if true ANCHORLINKS_WRAP_TEXT
true
whether to wrap the heading text in the anchor, if true ANCHORLINKS_TEXT_PREFIX
""
raw html prefix. Added before heading text, wrapped or unwrapped ANCHORLINKS_TEXT_SUFFIX
""
raw html suffix. Added before heading text, wrapped or unwrapped ANCHORLINKS_ANCHOR_CLASS
""
class for the a
tag
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:
IGNORE_BLANK_LINE
false
aside block will include blank lines between aside blocks and treat them as if the blank lines are also preceded by the aside block marker EXTEND_TO_BLANK_LINE
false
aside blocks extend to blank line when true. Enables more customary a la block quote parsing than commonmark strict standard ALLOW_LEADING_SPACE
true
when true
leading spaces before >
are allowed INTERRUPTS_ITEM_PARAGRAPH
true
when true
block quotes can interrupt list item text, else need blank line before to be included in list items INTERRUPTS_PARAGRAPH
true
when true
block quote can interrupt a paragraph, else needs blank line before WITH_LEAD_SPACES_INTERRUPTS_ITEM_PARAGRAPH
true
when true
block quotes with leading spaces can interrupt list item text, else need blank line before or no leading spaces
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_
to AsideExtension
key name to get Parser
block quote key name).
⚠️ This can potentially break code relying on versions of the extension before 0.40.20
because 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)
Converts attributes {...}
syntax into attributes AST nodes and adds an attribute provider to set attributes for immediately preceding sibling element during HTML rendering. See Attributes 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
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.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:
COLON_MARKER
true
enable use of :
as definition item marker MARKER_SPACES
1
minimum number of spaces after definition item marker for valid definition item TILDE_MARKER
true
enable use of ~
as definition item marker DOUBLE_BLANK_LINE_BREAKS_LIST
false
When true double blank line between definition item and next definition term will break a definition list FORMAT_MARKER_SPACES
3
formatting option see: Markdown Formatter FORMAT_MARKER_TYPE
DefinitionMarker.ANY
formatting option see: Markdown Formatter
ℹ️ 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
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
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 overridesATTR_IMAGE_SIZE
, default "20"
, attributes to use for rendering in the absence of attribute provider overridesATTR_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. See Emoji-Cheat-Sheet.com GitHub Repository repository for image files located in public/graphics/emojis
directory.USE_UNICODE_FILE_NAMES
, default false
. When true will use unicodeSampleFile
field for Emoji 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 linkEmojiImageType.UNICODE_ONLY
convert to unicode and if there is no unicode treat as invalid emoji shortcutEmojiImageType.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-sheetUsed 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.
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.
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 URLGIT_HUB_ISSUE_URL_PREFIX
: default "/"
override prefix used for appending the issue number to URLGIT_HUB_ISSUE_URL_SUFFIX
: default ""
override suffix used for appending the issue number to URLGIT_HUB_ISSUE_HTML_PREFIX
: default ""
override HTML to use as prefix for the issue textGIT_HUB_ISSUE_HTML_SUFFIX
: default ""
override HTML to use as suffix for the issue textEnables 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 overrideSTRIKETHROUGH_STYLE_HTML_CLOSE
: default (String)null
override HTML to use for wrapping style, if null then no overrideSUBSCRIPT_STYLE_HTML_OPEN
: default (String)null
override HTML to use for wrapping style, if null then no overrideSUBSCRIPT_STYLE_HTML_CLOSE
: default (String)null
override HTML to use for wrapping style, if null then no overrideEnables 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:
ITEM_DONE_MARKER
<input
type="checkbox"
class="task-list-item-checkbox"
checked="checked"
disabled="disabled" />
string to use for the item done marker html. ITEM_NOT_DONE_MARKER
<input
type="checkbox"
class="task-list-item-checkbox"
disabled="disabled" />
string to use for the item not done marker html. ITEM_CLASS
"task-list-item"
tight list item class attribute ITEM_ITEM_DONE_CLASS
""
list item class for done task list item ITEM_ITEM_NOT_DONE_CLASS
""
list item class for not done task list item LOOSE_ITEM_CLASS
value of ITEM_CLASS
loose list item class attribute, if not set then will use value of tight item class PARAGRAPH_CLASS
""
p tag class attribute, only applies to loose list items FORMAT_LIST_ITEM_CASE
TaskListItemCase.AS_IS
formatting option see: Markdown Formatter FORMAT_LIST_ITEM_PLACEMENT
TaskListItemPlacement.AS_IS
formatting option see: Markdown Formatter
TaskListItemCase
AS_IS
: no changeLOWERCASE
: change [X]
to [x]
UPPERCASE
: change [x]
to [X]
TaskListItemPlacement
AS_IS
: no changeINCOMPLETE_FIRST
: sort all lists to put incomplete task items firstINCOMPLETE_NESTED_FIRST
: sort all lists to put incomplete task items or items with incomplete task sub-items firstCOMPLETE_TO_NON_TASK
: sort all lists to put incomplete task items first and change complete task items to non-task itemsCOMPLETE_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 itemsEnables 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 URLGIT_HUB_USER_URL_PREFIX
: default "/"
override prefix used for appending the user name to URLGIT_HUB_USER_URL_SUFFIX
: default ""
override suffix used for appending the user name to URLGIT_HUB_USER_HTML_PREFIX
: default "<strong>"
override HTML to use as prefix for the user name textGIT_HUB_USER_HTML_SUFFIX
: default "</strong>"
override HTML to use as suffix for the user name textParses and renders GitLab 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 $``$
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 of Katex 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:
<link rel="stylesheet" href="katex.min.css"> <script src="katex.min.js"></script> <script src="mermaid.min.js"></script>
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:
<script> (function () { document.addEventListener("DOMContentLoaded", function () { var mathElems = document.getElementsByClassName("katex"); var elems = []; for (const i in mathElems) { if (mathElems.hasOwnProperty(i)) elems.push(mathElems[i]); } elems.forEach(elem => { katex.render(elem.textContent, elem, { throwOnError: false, displayMode: elem.nodeName !== 'SPAN', }); }); }); })();
Not really an extension but useful if you need to convert HTML to Markdown.
Converts HTML to Markdown, assumes all non-application specific extensions are going to be used:
This converter has an extension API to allow custom HTML tag to Markdown conversion, link URL replacement and options.
Use class FlexmarkHtmlConverter
in artifact flexmark-html2md-converter
.
Use FlexmarkHtmlConverter.builder(options).build().convert(htmlString)
to get equivalent to old FlexmarkHtmlParser.parse(htmlString, options)
The following options are available:
Defined in FlexmarkHtmlConverter
class:
BR_AS_EXTRA_BLANK_LINES
default true
, when true <br>
encountered after a blank line is already in output or current output ends in <br>
then will insert an inline HTML <br>
into output to create extra blank lines in rendered result.
BR_AS_PARA_BREAKS
default true
, when true <br>
encountered at the beginning of a new line will be treated as a paragraph break
CODE_INDENT
, default 4 spaces, indent to use for indented code
DEFINITION_MARKER_SPACES
, default 3
, min spaces after :
for definitions
DIV_AS_PARAGRAPH
default false
, when true will treat <div>
wrapped text as if it was <p>
wrapped by adding a blank line after the text.
DOT_ONLY_NUMERIC_LISTS
, default true
. When set to false closing parenthesis as a list delimiter will be used in Markdown if present in MS-Word style list. Otherwise parenthesis delimited list will be converted to dot .
.
EOL_IN_TITLE_ATTRIBUTE
, default " "
, string to use in place of EOL in image and link title attribute.
LISTS_END_ON_DOUBLE_BLANK
default false
, when set to true
consecutive lists are separated by double blank line, otherwise by an empty HTML comment line.
LIST_CONTENT_INDENT
, default true
, continuation lines of list items and definitions indent to content column otherwise 4 spaces
MIN_SETEXT_HEADING_MARKER_LENGTH
, default 3
, min 3, minimum setext heading marker length
MIN_TABLE_SEPARATOR_COLUMN_WIDTH
, default 1
, min 1, minimum number of -
in separator column, excluding alignment colons :
MIN_TABLE_SEPARATOR_DASHES
, default 3
, min 3, minimum separator column width, including alignment colons :
NBSP_TEXT
, default " "
, string to use in place of non-break-space
ORDERED_LIST_DELIMITER
, default '.'
, delimiter for ordered items
OUTPUT_UNKNOWN_TAGS
, default false
, when true unprocessed tags will be output, otherwise they are ignored
RENDER_COMMENTS
, default false
. When set to true HTML comments will be rendered in the Markdown.
SETEXT_HEADINGS
, default true
, if true then use Setext headings for h1 and h2
THEMATIC_BREAK
, default "*** ** * ** ***"
, <hr>
replacement
UNORDERED_LIST_DELIMITER
, default '*'
, delimiter for unordered list items
OUTPUT_ATTRIBUTES_ID
, default true
, if true
id attribute will be rendered in Attributes syntax
OUTPUT_ID_ATTRIBUTE_REGEX
, default "^user-content-(.*)"
, regex to use for processing id attributes, if matched then will concatenate all groups which are not empty, if result string is empty after trimming then no id will be generated. If value empty then no processing is done and id will be rendered as in the HTML.
ℹ️ Default value will strip out GitHub rendered HTML heading id prefix of user-content-
.
OUTPUT_ATTRIBUTES_NAMES_REGEX
default ""
, if not empty then will output attributes extension syntax for attribute names that are matched by the regex.
ADD_TRAILING_EOL
, default false
. Will add trailing EOL to generated markdown text.
to convert some markdown formatting elements to their inner text, default for all is false:
SKIP_HEADING_1
- heading 1SKIP_HEADING_2
- heading 2SKIP_HEADING_3
- heading 3SKIP_HEADING_4
- heading 4SKIP_HEADING_5
- heading 5SKIP_HEADING_6
- heading 6SKIP_ATTRIBUTES
- attribute extension conversionSKIP_FENCED_CODE
- skip fenced code extension conversionSKIP_LINKS
- convert links to plain textSKIP_CHAR_ESCAPE
- no escaped characters conversionto control conversion of inline elements, default is ExtensionConversion.MARKDOWN
EXT_INLINE_STRONG
- strongEXT_INLINE_EMPHASIS
- emphasisEXT_INLINE_CODE
- codeEXT_INLINE_DEL
- delEXT_INLINE_INS
- insEXT_INLINE_SUB
- subEXT_INLINE_SUP
- supAvailable settings:
ExtensionConversion.MARKDOWN
- convert to markdownExtensionConversion.TEXT
- convert to inner textExtensionConversion.HTML
- leave HTML as isUNWRAPPED_TAGS
, default new String[] { "article", "address", "frameset", "section", "small", "iframe", }
, defines tags whose inner html content should be rendered
WRAPPED_TAGS
, default new String[] { "kbd", "var" }
, defines tags which should render as outer HTML. Inner text will be converted to markdown.
TYPOGRAPHIC_REPLACEMENT_MAP
option key taking a Map<String,String>
, if not empty will be used instead of the bundled map. Any typographic characters or HTML entities missing from the map will be output without conversion. If you want to suppress a typographic so it is not output add ""
to its mapped value.
The bundled map is filled as follows:
class HtmlParser { static Map<String, String> specialCharsMap = new HashMap<>(); static { specialCharsMap.put("“", "\""); specialCharsMap.put("”", "\""); specialCharsMap.put("“", "\""); specialCharsMap.put("”", "\""); specialCharsMap.put("‘", "'"); specialCharsMap.put("’", "'"); specialCharsMap.put("‘", "'"); specialCharsMap.put("’", "'"); specialCharsMap.put("'", "'"); specialCharsMap.put("«", "<<"); specialCharsMap.put("«", "<<"); specialCharsMap.put("»", ">>"); specialCharsMap.put("»", ">>"); specialCharsMap.put("…", "..."); specialCharsMap.put("…", "..."); specialCharsMap.put("–", "--"); specialCharsMap.put("&endash;", "--"); specialCharsMap.put("—", "---"); specialCharsMap.put("&emdash;", "---"); } }
For controlling how the converted HTML tables are rendered in markdown you can use any of the Formatter
table options since formatter is used by the HTML parser to render tables.
Uses the excellent jsoup HTML parsing library and emoji shortcuts using Emoji-Cheat-Sheet.com
Enables ins tagging of text by enclosing it in ++
. For example, in hey ++you++
, you
will be rendered as inserted text.
Use class InsExtension
in artifact flexmark-ext-ins
.
The following options are available:
Defined in InsExtension
class:
INS_STYLE_HTML_CLOSE
: default (String)null
override HTML to use for wrapping style, if null then no overrideINS_STYLE_HTML_OPEN
: default (String)null
override HTML to use for wrapping style, if null then no overrideAllows rendering of Jekyll {% tag %}
with and without parameters.
Use class JekyllTagExtension
in artifact flexmark-ext-jekyll-tag
.
ℹ️ you can process the include tags and add the content of these files to the INCLUDED_HTML
map so that the content is rendered. If the included content starts off as Markdown and may contain references that are used by the document which includes the file, then you can transfer the references from the included document to the including document using the Parser.transferReferences(Document, Document)
. See: JekyllIncludeFileSample.java
The following options are available:
Defined in JekyllTagExtension
class:
ENABLE_INLINE_TAGS
true
parse inline tags. ENABLE_BLOCK_TAGS
true
parse block tags. ENABLE_RENDERING
false
render tags as text INCLUDED_HTML
(Map<String, String>)null
map of include tag parameter string to HTML content to be used to replace the tag element in rendering LIST_INCLUDES_ONLY
true
only add includes tags to TAG_LIST if true, else add all tags TAG_LIST
new ArrayList<JekyllTag>()
list of all jekyll tags in the document
Allows rendering of the markdown AST as JIRA formatted text
Use class JiraConverterExtension
in artifact flexmark-jira-converter
.
No options are defined. Extensions that do no support JIRA formatting will not generate any output for their corresponding nodes.
Macro Definitions are block elements which can contain any markdown element(s) but can be expanded in a block or inline context, allowing block elements to be used where only inline elements are permitted by the syntax. Macros Extension
Use class MacroExtension
in artifact flexmark-ext-macros
.
Media link transformer extension courtesy Cornelia Schultz (GitHub @CorneliaXaos) transforms links using custom prefixes to Audio, Embed, Picture, and Video HTML5 tags.
!A[Text](link|orLinks)
- audio!E[Text](link|orLinks)
- embed!P[Text](link|orLinks)
- picture!V[Text](link|orLinks)
- videoUse class MediaTagsExtension
in artifact flexmark-ext-media-tags
.
No options are defined.
Resizable Image ExtensionAdds image size syntax to image URL. 
where =WxH
is the width
and height
attribute values for the image, px
suffix will be added to the numerical values.
Use class ResizableImageExtension
in artifact flexmark-ext-resizable-image
.
No options are defined.
⚠️ This extension is a user contribution and will not be supported in the future. Its implementation does not follow the flexmark-java parser extension model, it does not implement any renderers other than HTML and does not provide any text details of the source elements in its AST.
Use at your own discretion.
Parses the flexmark extended spec examples into example nodes with particulars broken and many rendering options. Otherwise these parse as fenced code. Flexmark Spec Example Extension
This extension is used by Markdown Navigator plugin for JetBrains IDEs to facilitate work with flexmark-java test spec files.
Enables ins tagging of text by enclosing it in ^
. For example, in hey ^you^
, you
will be rendered as superscript text.
Use class SuperscriptExtension
in artifact flexmark-ext-superscript
.
The following options are available:
Defined in SuperscriptExtension
class:
SUPERSCRIPT_STYLE_HTML_CLOSE
: default (String)null
override HTML to use for wrapping style, if null then no overrideSUPERSCRIPT_STYLE_HTML_OPEN
: default (String)null
override HTML to use for wrapping style, if null then no overrideEnables tables using pipes as in GitHub Flavored Markdown. With added options to handle column span syntax, ability to have more than one header row, disparate column numbers between rows, etc. Tables Extension
Table of contents extension is really two extensions in one: [TOC]
element which renders a table of contents and a simulated [TOC]:#
element which also renders a table of contents but is also intended for post processors that will append a table of contents after the element. Resulting in a source file with a table of contents element which will render on any markdown processor.
Use class TocExtension
or SimTocExtension
in artifact flexmark-ext-toc
.
For details see Table of Contents Extension
Converts plain text to typographic characters. Typographic Extension
'
to apostrophe ’
’...
and . . .
to ellipsis …
…--
en dash –
–---
em dash —
—'some text'
to ‘some text’
‘some text’"some text"
to “some text”
“some text”<<some text>>
to «some text»
«some text»Enables wiki links [[page reference]]
and optionally wiki images ![[image reference]]
To properly resolve wiki link to URL you will most likely need to implement a custom link resolver to handle the logic of your project. Please see: PegdownCustomLinkResolverOptions
Use class WikiLinkExtension
in artifact flexmark-ext-wikilink
.
The following options are available:
Defined in WikiLinkExtension
class:
ALLOW_INLINES
false
to allow delimiter processing in text part when ` DISABLE_RENDERING
false
disables wiki link rendering if true wiki links render the text of the node. Used to parse WikiLinks into the AST but not render them in the HTML IMAGE_LINKS
false
enables wiki image link format ![[]]
same as wiki links but with a !
prefix, alt text is same as wiki link text and affected by LINK_FIRST_SYNTAX
IMAGE_PREFIX
""
Prefix to add to the to generated link URL IMAGE_PREFIX_ABSOLUTE
value of IMAGE_PREFIX
Prefix to add to the to generated link URL for absolute wiki links (starting with /
) IMAGE_FILE_EXTENSION
""
Extension to append to generated link URL LINK_FIRST_SYNTAX
false
When two part syntax is used `[[first LINK_PREFIX
""
Prefix to add to the to generated link URL LINK_PREFIX_ABSOLUTE
value of LINK_PREFIX
Prefix to add to the to generated link URL for absolute wiki links (starting with /
) LINK_FILE_EXTENSION
""
Extension to append to generated link URL LINK_ESCAPE_CHARS
" +/<>"
characters to replace in page ref by replacing them with corresponding characters in LINK_REPLACE_CHARS
LINK_REPLACE_CHARS
"-----"
characters to replace in page ref by replacing corresponding characters in LINK_ESCAPE_CHARS
Application provided macros of the form {{macroName}}content{{/macroName}}
or the block macro form:
{{macroName}} content {{/macroName}}
Use class MacroExtension
in artifact flexmark-ext-xwiki-macros
.
The following options are available:
Defined in MacroExtension
class:
ENABLE_INLINE_MACROS
true
enable inline macro processing ENABLE_BLOCK_MACROS
true
enable block macro processing ENABLE_RENDERING
false
enable rendering of macro nodes as text
Adds support for metadata through a YAML front matter block. This extension only supports a subset of YAML syntax. Here's an example of what's supported:
--- key: value list: - value 1 - value 2 literal: | this is literal value. literal values 2 --- document starts here
Use class YamlFrontMatterExtension
in artifact flexmark-ext-yaml-front-matter
. To fetch metadata, use YamlFrontMatterVisitor
.
Allows rendering of the markdown AST as YouTrack formatted text
Use class YouTrackConverterExtension
in artifact flexmark-youtrack-converter
.
No options are defined. Extensions that do no support YouTrack formatting will not generate any output for their corresponding nodes.
YouTube Embedded Link TransformerYouTube link transformer extension courtesy Vyacheslav N. Boyko (GitHub @bvn13) transforms simple links to youtube videos to embedded video iframe.
Use class YouTubeLinkExtension
in artifact flexmark-ext-youtube-embedded
.
No options are defined.
Converts simple links to youtube videos to embedded video HTML code.
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4