Visit GitHub Repo
IDE Plugins

Markdown Navigator 2.8

Table of Contents



Markdown language support for IntelliJ platform

A Markdown plugin with GFM and a matching preview style.

You can download it on the JetBrains plugin page.

Get Markdown Navigator enhanced edition to unlock all productivity features.

Document with pleasure!

Work with Markdown files like you do with other languages in the IDE, by getting full support for:

  • Paste images into documents for fast screen capture links
  • Drag & Drop files and images for fast link insertion
  • Drag and Drop text, HTML or links from other applications
  • Formatting to cleanup documents with a key stroke
  • Navigation and Find Usages to find references without effort
  • Copy Markdown as JIRA, YouTrack or HTML formatted text
  • Convert HTML to Markdown by pasting it into a Markdown document.
  • Export to HTML or PDF to share with others
  • Refactoring of all referencing elements:
    • files ⟺ links
    • headings ⟺ ref anchors
    • footnotes ⟺ footnote refs
    • references ⟺ ref links/ref images
  • Completions to reduce typing:
    • link address ⇐ files
    • ref anchors ⇐ headings
    • footnote refs ⇐ footnotes
    • ref links/ref images ⇐ references
    • link text ⇐ ref anchor/link address
  • Error and Warning annotations to help catch mistakes early
  • Intention actions for fast results with less effort
  • Wrap on Typing to keep it nicely formatted as you edit
  • GitHub style rendering that you are used to, out of the box
  • GitLab parsing and rendering extensions
  • Math block and inline rendering by Katex or
  • PlantUML fenced code rendering by PlantUML or
  • Fast typing response for distraction free editing
  • Fully customizable to adjust to your preferences and project needs

Two tier model

  1. Previewing, syntax highlighting, basic editing functionality with link completions with split editor preview is available in the basic open source edition. Intended for mostly previewing and editing of markdown documents without full document format.

  2. Advanced features used for creating and maintaining markdown documents: refactoring, find usages, validation and auto formatting are only available in the Enhanced licensed version. 15-day free trial licenses are available from Markdown Navigator page on my website.

Release Road Map

Future Release: Version 3.0.0

Major Refactoring Release

  • Improved Multiple Module Support
  • Link resolution support for non-GitHub VCS providers
  • Plus the usual bug fixes that come up between now and the release.

Version 2.8.4

Bug and compatibility fixes you can find in Version Notes.

Install EAP plugin version to preview next release.

  • Java 11 JRE Support
  • Improved Preview and Typing response
  • Cut/Copy/Paste Improved to handle Macros, Enumerated References and Link adjustments.
  • Copy/Paste between IDE instances with all references and links properly included and adjusted.
  • Plain Text Completions to insert references defined in file and in project scope. See: Plain Text Suggestion Scope
  • Inspection Option to ignore markdown text in fenced code
  • New Inspections
    • mismatch of link to heading text for anchor refs to headings
    • unicode LINE SEPARATOR in file
    • when a list item needs more indentation to be a sub-item
  • Annotator Settings to customize enabled annotations
  • Annotator Errors to show underline for file in project tree
  • New Intentions to wrap auto-link looking text in <>
  • New HTML Paste Options convert links to: references, text, HTML or explicit links
  • New Structure View Option Show Headings & Tasks
  • Show Members in project view to show headings
  • Format Document option to remove unused reference element definitions.
  • In-place Rename of headings, references and other elements
  • Dropped Links insert options: Link, Ref Link & Reference, Reference Only
  • Syntax Highlighter Attributes for GitLab extension elements
  • Comment directive to Ignore invalid link or anchor for annotation
  • Create PDF Export profile, see Configuring for Non-Latin Character Sets
  • Default Completion format setting to change starting link address format.

Version 2.8.2

  • Enhanced edition features migrated to basic edition:
    • Extensions: Jekyll Front Matter
    • Inspections: GitHub Table, Jekyll Front Matter, Emoji Shortcut
    • Completions: Emoji shortcuts, Links, References, Fenced code language
    • Editor Settings: Language Injections, Remove prefix when joining lines, Simple structure view
    • Actions and Toolbar buttons:
      • Toggle inline styles
      • Block quote actions
      • List actions
      • Insert table action
      • Format Element
    • Wrap on typing
  • Create PDF Export profile for non-Latin character sets
  • Drag and Drop text, HTML or links from other applications
  • Copy PlantUML image intention to copy diagram to clipboard
  • Convert between images and Math block and inline
  • Convert between images and PlantUML fenced code
  • Math block and inline rendering by Katex or
  • PlantUML fenced code rendering via PlantUML library or
  • Multi-Line Image URL language injections
  • GitHub Issue completions insert link to issue
  • Show HTML page as Documentation for GitHub issues and optionally for URLs
  • Improved Directory/Package Refactoring for all IDEs
  • Improved: toolbar actions dealing with block quotes, list items, heading level up/down to handle conversion to/from plain text.
  • New: heading style conversion during document format
  • New: Convert fenced code to indented code intention
  • New: Copy Exported as HTML Mime Content Action to copy HTML export text as HTML mime content
  • New: Image Paste highlight option to annotate an area of the image.
  • New: Copy markdown without soft line breaks copies document or selection to the clipboard eliminating soft line breaks. Useful when copying wrapped markdown to GitHub comments.
  • New: All copy markdown actions: CopyHtmlMimeFormattedAction, CopyJiraFormattedAction, CopyNoSoftLineBreaksAction and CopyYouTrackFormattedAction, now include all reference defining elements which were referenced from the copied part. All links and other elements resolve without needing to include their reference definitions in the selection.
  • New: option for full highlight attributes, enabled takes 3700 attributes out of the pool, while disabled less than 300.

Source Update is Long Overdue

Now that I unified the display between the licensed and unlicensed versions by removing support for preview tabs in favour of split editor as the only option, I will be updating the open source with a new version much easier.

The update will be more like a replacement of the source than an evolution of it. The directory structure has changed significantly and a lot of Java has been converted to Kotlin.

The enhanced version is now 120k lines of code so my goal is to separate the open source functionality from the proprietary code with a clean boundary to make open source releases synchronized with plugin releases like they used to be but without the need for manual merging between the two.

Working with the source

IntelliJ Plugin SDK development environment.

Some internal details, should you care to know

The pegdown Markdown parser used by the plugin in its original incarnation was changed to flexmark-java and pegdown dependencies have been removed as of version 2.2.0.

flexmark-java is a fork of commonmark-java, with changes:

  • source element based AST with detailed break down of each element for syntax highlighting
  • complete source position tracking for all elements and their lexical parts
  • optimized for efficient parsing with many parser extensions installed
  • unified core and extension options API to simplify parser/renderer configuration
  • options to tweak core parser rules

In the process of making the needed modifications to the original commonmark-java parser, performance was impacted by about 25-35%. This still makes the new parser 7x-10x faster than intellij-markdown parser used by Markdown Support and 25x-50x faster than pegdown. As an added benefit, the new parser does not suffer from pegdown's idiosyncrasies of exponential parse times or pathological input cases that cause infinite loops in the parser's state machine.

On the coding end, the new parser is a joy to maintain and enhance. The parser architecture, inherited from commonmark-java, is easy to debug and test. Markdown element parsers have little or no interdependencies with other element parsers making it easy to fine tune parser behaviour on a per element basis and add parser configuration options to emulate other markdown processors. All this is in contrast to pegdown's one big PEG grammar implementation with everything potentially inter-dependent.


It all started with a desire to see Markdown files in PhpStorm IDE as they would look on GitHub. I was already using nicoulaj/idea-markdown plugin but found its preview was more like Craig's List than GitHub. It did not appear to have been recently updated, so I decided to fork it and modify its style sheet. How hard could that be?

I found out quickly that there was more to it than meets the eye. Rendering is done by Swing not a browser, the parser is HTML 3.1, with many features not implemented. Additionally, the Table extension did not work in pegdown version used by the plugin.

I upgraded the plugin to use the latest pegdown, parboiled. Fixed a few bugs. I was already in the code so I might as well add a few more features like user editable style sheet, fix a few more bugs, add updates to preview so that I could split the editor pane and edit in one while seeing the preview in the other.

Now almost four years later, the plugin is brimming with features to make Markdown editing and creation a breeze. It was more work than I imagined but more satisfying that I had hoped.

It has been a fun trip down the rabbit hole of IntelliJ IDEA plugin development which started with a simple desire for a Markdown preview that looked like GitHub's.

* This plugin was originally based on the nicoulaj/idea-markdown plugin by nicoulaj, which was based on pegdown library by sirthias.

Markdown Navigator, Copyright (c) 2015-2019, V. Schneider, All Rights Reserved.

Watch and learn from our free Android videos