Add Support GitLab Parser

[Javaru]

As a feature request, I'd like to see GitLab parser support added, i,e. GitLab Flavored Markdown (GFM). I understand adding a new parser is a significant undertaking. Nevertheless, GitLab is gaining in popularity. This is particularity true in the corporate space since it can be used free (community version) or at a substantially lower cost than GitHub (enterprise version). For example my employer (45k employees, ~10k of which are developers) uses GitLab for its corporate VCS. GitLab Flavored Markdown support would give me one more talking point when talking up the value of Markdown Navigator to my co-workers and management since we are an IntelliJ IDEA based shop.

GitLab Flavored Markdown uses the Redcarpet Ruby library for Markdown processing. More detail at the GitLab Markdown information page.

[vsch]

@Javaru,

I took a look at the GitLab markdown flavour and found that most of its constructs are already supported except for the delimiting block quote markers >>> and the GitLab specific issue, pr and user syntax.

I have not tested GitLab for its markdown indentation handling, which is the other markdown compatibility nightmare but suspect that is probably close to one of already implemented flavours in the flexmark-java library.

The real issue with supporting other markdown parsers is not so much the markdown quirks, most of which are easily implemented, it is the link resolution logic and associated completion search logic.

What has kept me from venturing into systems other than GitHub is the need to rework the link resolution part of the plugin to make it more flexible and modular. I have rewritten this part of the code four times since initial plugin implementation. Every time, I thought the final re-write would be flexible enough but as I discovered all the idiosyncrasies of actual use cases and limitations of the implementation found that it is still a pain to debug and maintain.

The latest implementation has proven to be the most long lasting but still no cigar in terms of making it good enough to be easily adjustable to link resolution logic of other processors.

I noted that GitHub and GitLab wikis have different link resolutions, including GitLab does not have wiki links of the form [[page ref]]. I think that links to files in the main repo are the same as GitHub however idiosyncrasies of handling links to raw image files are probably different.

All that to say that I will be re-writing the link resolution architecture to address ability to implement multiple implementations including non-GitHub ones but this is not a small effort that can be done in a few days.

[Javaru]

@vsch

Thanks for the detailed and thoughtful response. I figured this would be a more long-term request. I, as I'm sure most developers, can relate to the challenge it is to abstract some domain spaces out into a flexible, yet simple and maintainable, API. We've all rewritten APIs "for the final time" many times. I hope you are able to achieve your goals and then perhaps add GitLab to the available parsers/renders.

I do find that the current renders are pretty close. But I do run into some issues from time to time that after pushing a change the document and viewing it on GitLab, it needs to be tweaked due to layout/formatting issues that did not present themselves in Markdown Navigator's preview. This then results in the need to make numerous pushes in a trial and error routine.

If it would be helpful to you, I'd be happy to update this ticket as I run across any discrepancies so you can have a running list (knowing that it may be quite some time before you are able to implement this, if ever). I just would not want to do that if it would come across as my being pushy, or if ultimately it would not be useful to you based on how the parser and render is actually implemented (since I have no experience in visual document parsing and rendering, only data extraction parsing.)

Thanks!

[vsch]

@Javaru, please do provide any discrepancies you find in the parsing and rendering between the plugin and GitLab.

From the documentation I think that the best compatibility with GitLab is probably achieved via Old GitHub Doc for list in the parser settings, which was the parsing rules used by GitHub before they upgraded to CommonMark compatible parsing:

I will be able to address most, if not all, of the parsing/rendering discrepancies before I rewrite the link resolver since the link resolver only affects the document and site relative links, not the parsing and rendering.

As soon as I have one of these implemented I will add a GitLab parsing profile and corresponding options to parser settings.

I will also start compatibility testing with GitLab markdown to find discrepancies between CommonMark and Redcarpet implementation. From past experience this effort will find some differences but many edge use cases will be undetected.

Right now there are the following markdown elements which differ:

• [x] Multiline Block quote delimiters >>>
• [x] Deleted text markers {- -} or [- -]
• [x] Inserted text markers {+ +} or [+ +]
• [x] Video links are not converted to embedded video
• [x] Header ids with emoji shortcuts generate an extra - because of two spaces around the emoji shortcut while GitLab only generates a single -. I suspect that multiple spaces in header text will not generate multiple - in the id on GitLab while they do in Markdown Navigator.
• [x] Math, inline via $``$ or as fenced code with math info string, probable workaround is to include Katex into the rendered HTML page but adding support to parser/renderer is a better choice. I did some testing with MathJax see: https://github.com/vsch/idea-multimarkdown/issues/467
• [x] Graphing via Mermaid as fenced code with mermaid info string, probably implementable via Mermaid inclusion similar to MathJax solution above.

[vsch]

@Javaru, added GitLab Flavoured Markdown parsing and rendering functionality

• Math inline using $``$ and fenced code blocks with info of math using Katex
• Charts fenced code blocks with info of mermaid using Mermaid
• Ins/Del via {++} and [++]/{--} and [--]
• Multi-line block quotes
• Video image link rendering

This only applies to parsing and rendering HTML not the style sheet. Also link completions are GitHub like. The latter is for release 3.0.

EAP update with a fix for the issue is available.

To enable EAP update channel:

1. Select "Early Access Program" in Check updates for:
2. Then make the IDE check for updates.