Markdown Merge API

Formatter doubles as a merge renderer to combine multiple markdown documents into a single document while trying to preserve reference resolution within each document.

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

This is done by adding a numeric sequence to any references which create a conflict definition between documents.

ℹ️ By default flexmark-ext-abbreviation extension elements do not change abbreviation and abbreviation definitions to make them unique since abbreviations are expected to be defined to the same values across documents and adding a numeric suffix would change the displayed text. However, this behavior can be changed by setting AbbreviationExtension.MAKE_MERGED_ABBREVIATIONS_UNIQUE to true in the formatter options used to merge the documents.

Relative Link Resolution

If Formatter.DEFAULT_LINK_RESOLVER property is set to true then doc relative and doc root relative (ones starting with /) will be changed in each document to a link prefixed with Formatter.DOC_RELATIVE_URL or Formatter.DOC_ROOT_URL property set on each merged document. This allows all links and image references to be mapped a link which will resolve to the correct target in the merged document. These properties should be set to either the full path prefix for the document or some prefix which will result in merged document links to resolve properly. The details of what this value should be does not depend on this library but on the link resolution used for rendering the merged document and its doc relative and doc root URL properties.

API

• Formatter.mergeRender(Document[] documents, Appendable out, int maxBlankLines, HtmlIdGeneratorFactory idGeneratorFactory) - is the most general api, with:
  • documents is the list of documents to be merged.
  • out the appendable for merged document output
  • maxBlankLines the maximum number of blank lines to allow after each document in the merged result
  • idGeneratorFactory is the HTML id generator factory to use for generating heading ids. If null then default HTML renderer header id generator will be used.
• void Formatter.mergeRender(Document[], Appendable, HtmlIdGeneratorFactory), will use void Formatter.MAX_TRAILING_BLANK_LINES property for maxBlankLines, the rest as above
• String Formatter.mergeRender(Document[], int, HtmlIdGeneratorFactory), will return the string value of the resulting merged document.

Sample code: FormatterMergeSample.java

Conflicting Heading Ids

Conflicting headings in merged document will result in unique heading id added as an explicit attribute if the flexmark-ext-attributes extension is used. This will map local heading references to the unique id resulting in correct header reference within a file. If the attributes extension is not used then no unique id will be generated and all local heading links will refer to the first matching heading.

Merging the following documents:

# Heading

[](#heading) 

# Heading

[](#heading) 

Will result in the merged markdown file:

# Heading

[](#heading) 

# Heading {#heading1}

[](#heading1) 

Custom Reference Element Merge

Merge functionality is implemented using the formatter translation API without actually changing any text, only references. This means that any custom reference elements which implement translation rendering using the NodeRepositoryFormatter<> base class will be merge capable.

For examples of how references are handled it is best to reference implementation of core elements in CoreNodeFormatter.java or extensions:

• AbbreviationNodeFormatter.java
• AdmonitionNodeFormatter.java
• AttributesNodeFormatter.java
• EmojiNodeFormatter.java
• EnumeratedReferenceNodeFormatter.java
• FootnoteNodeFormatter.java