Parser Settings

Markdown Navigator uses open source flexmark-java markdown parser library which comes with many extensions. Most of these extensions are configurable in the plugin in the parser settings tab under Languages & Frameworks > Markdown > Parser:

Parser Profile

• GitHub Markdown Documents: Parser options for standard repository GitHub documents
• GitHub Comments: Parser options for GitHub comments in issues and pull requests
• GitHub Wiki Pages: Parser options for GitHub wiki pages
• GitBook Markdown Documents: Parser options for GitBook documents
• CommonMark: Parser options for standard CommonMark, without any extensions
• Custom: custom parser configuration

Github Extensions

These are GitHub supported extensions which are enabled for GitHub based profiles.

• Auto links
• Anchor links
• Emoji Icons: parses emoji shortcuts of the form :shortcut:
• Fenced code blocks
• Strike-through using ~~ markup
• Tables using | to separate table columns. see Tables Extension
• Task lists, bullet or numbered lists with [ ], [x] or [X] following the list item marker.
• Wiki links, only applicable to markdown documents in wiki directory. see Adding GitHub Wiki to IntelliJ Project

Syntax Options

Configures parser extension syntax options:

• ATX header space: when set, requires a space after the opening ATX heading markers #.
• No duplicated dashes: when set heading ids generated from headings will not contain duplicated -
• Lowercase non-ascii text: when set heading ids generated from heading text will convert non-ASCII alphabetic characters to lowercase.
• Trim trailing spaces of reference link text: when set, reference link text in headings will have trailing blanks trimmed. ℹ️ GitHub does not trim this text for heading id generation.
• Hard wraps: when set, line breaks in markdown source are converted to <br> in rendered HTML.
• Relaxed HR syntax: when set, allows thematic breaks without a preceding blank line.
• Lists: options for parsing list item indentations
  • Old GitHub Docs: parsed according to GitHub documents rules before GitHub upgraded to CommonMark.
  • CommonMark: parsed by common mark rules
  • Fixed 4: parsed using fixed 4 spaces indentation. This is an option used by pegdown, PhpExtras, MultiMarkdown and other fixed indentation parsers.
• Old GitHub loose item rules: when set, pre-commonmark GitHub rules will be used for parsing and rendering loose list items. This setting turns off automatically forcing all list items to loose if a single list item is loose, or if a list items contains non-list item children. Use this to override CommonMark's dogmatic rules for setting list item loose status.
• GitHub Table rendering: table parsing will be done by GitHub rules. This means only one heading row is allowed, no column spans and number of columns in body must match number of columns in the heading.
• GitHub wiki links: when set GitHub wiki page rules are used where the wiki link format is [[wiki link text|wiki page ref]]. When clear then Creole wiki link rules will be used [[wiki page ref|wiki link text]].
• HTML block deep parsing: when set then HTML block source will be parsed for HTML content to determine when to close the HTML block as is done by pegdown and old GitHub markdown parser. When clear commonmark rules are used where the block is only parsed for opening tag and continues to a blank line.

Publishing

Extensions facilitating use of markdown for publishing.

• Abbreviations: adds abbreviation definitions of the form [*Abbr]: Abbreviation Title Text

• Admonition: Admonition Extension, Material for MkDocs used to created block styled side content in documentation. see: Admonition Extension

• Aside: adds an aside extension which has the same syntax as block quotes except | is used as the lead-in character. Admonition extension offers more options and more flexibility for side content with slightly more markup text.

• Attributes: parses HTML attributes of the form {attr=value}, {attr='value'}, {attr="value"}, {.class-name} or {#element-id}. see: Attributes Extension

• Definitions: adds definitions extension. Syntax is:

  Definition Term
  : Definition item

  • Break list on two blank lines: when set a new definition list is started on two blank lines

• Enumerated Reference: allows enumerated reference links and text. see: Enumerated References Extension

• Footnotes: footnote extension uses [^footnote]: footnote text to define the footnote content and [^footnote] to add a footnote reference in the text. see Footnotes Extension

• Underline: underlines or inserted text extension of the form ++underlined text++

• Subscript: sub-scripted text extension of the form ~subscript~

• Superscript: super-scripted text extension of the form ^superscript^

• Table of Contents: parse table of contents syntax of the form [TOC]: #. See Table of Contents Extension

  • Generate blank line spacer: when enabled adds a blank line between the [TOC]: # tag and the automatically generated table of contents for best markdown processor compatibility.

Typographic

Typographic characters conversion.

• Quotes: will convert quotes around text to their typographic opening and closing quotes
  • 'this' to ‘this’
  • "this" to “this”
  • <<this>> to «this»
• Ellipsis, Hyphens, Apostrophes: will convert
  • ... and . . . to …
  • l'ordre to l’ordre
  • -- to n-dash –
  • --- to m-dash —

Suppress

Used to suppress HTML parsing in markdown. HTML included in markdown will be removed during parsing

• HTML blocks: suppress HTML blocks
• Inline HTML: suppress inline HTML

Processor Extensions

Additional extensions which can be used to extend the functionality available in markdown documents:

• Jekyll Front Matter: parses Jekyll Front matter block at the start of the document and enables {% include "includedFile" %} processing. The included file path should be relative to the projects _includes/ directory and only files in it will be resolved or be available in completion list.

• GitBook compatibility mode: changes how links are processed to be compatible with GitBook encoding.

  ℹ️ This also changes the processing of {% include "includedFile" %}. GitLab uses page relative path for the included file. Jekyll uses a path relative to the project's _includes/ directory.

• GitLab Flavoured Markdown: Adds GitLab Flavoured Markdown parsing and rendering functionality

  • Math inline using $``$ and fenced code blocks with info of math using Katex
  • Chart fenced code blocks with info of mermaid using Mermaid
  • Inserted text (underlined) via {+text+} or [+text+]
  • Deleted text (strike through) via {-text-} or [-text-]
  • Multi-line block quotes using >>> at start of line to mark block start and >>> at start of line to mark block end. GFM: Multi-line Blockquote
  • Video image link rendering GFM: Videos

• GitLab math (Katex): enables math extension. If GitLab Flavoured Markdown is selected this is automatically enabled. Otherwise can be selected separately from GitLab extensions above.

  ℹ️ Math block and inline rendering can be done with Katex JavaScript in the JavaFX preview browser or via CodeCogs latex image rendering URL set by Html Generation Settings: math rendering

• GitLab charts (Mermaid): enables charts extension. if GitLab Flavoured Markdown is selected this is automatically enabled. Otherwise can be selected separately from GitLab extensions above.

• Macros: enables macro extension. Used to define and then expand macros as inline macro reference element. Macros Extension

• PlantUML fenced code (puml language): enables fenced code with puml language string to be rendered as PlantUML chart. Type of rendering set by Html Generation Settings: plantuml rendering

• DOT fenced code (plantuml language): enables fenced code with plantuml language string to be rendered as DOT chart. Type of rendering set by Html Generation Settings: plantuml rendering