Markdown Navigator 3.0

Table of Contents

• Overview
  • Document with pleasure!
  • Two tier model
  • Source
• Background

Overview

Markdown language support for IntelliJ platform

You can download it on the JetBrains plugin page.

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 clean up documents with a keystroke
• 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 extension using Katex
  • Charts extension using Mermaid
• Math block and inline rendering by Katex or codecogs.com
• PlantUML fenced code rendering by PlantUML or gravizo.com
• 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 were available with the Enhanced version, from the JetBrains Marketplace.

   :information_source: The latest release is only to address compatibility issues for newer IDEs from 2021.3 to 2023.1.1.

   It is a full-featured Enhanced version, released without needing a license.

   It is only intended as a measure to allow users, who depended on this plugin for their workflow, to have a working solution until I can figure out if it is possible to continue maintaining this plugin in an economically sustainable manner and return Markdown Navigator Enhanced to the JetBrains Marketplace as a paid plugin, or let it go for good.

Source

The source in this repository is for the unlicensed version of the plugin. As such, it does not have all the features of the enhanced version.

Working with the source

IntelliJ Gradle Plugin development environment. See Building from sources

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

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.

Background

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, years later, the plugin is brimming with features to make Markdown editing and creation a breeze. It was a lot more work, and code, 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-2023, Vladimir Schneider, All Rights Reserved.