Extension of JIRA render to support Confluence wiki markup

[qwazer]

I want to use your wonderful library in 2 projects:

1. https://github.com/bsorrentino/maven-confluence-plugin
2. https://github.com/qwazer/markdown-confluence-gradle-plugin
   instead of PegDown.

Basically, flexmark-jira-converter fill all my needs except a couple of items:

1. Ref links between pages confluence-wiki-markup.
   Plugins above use specific logic and add page title prefixes to confluence page names, so to support ref links between pages I need to repeat the same logic when I render RefLink object.

2. The custom format of admonitions. Plugins above use the custom format for admonitions

> **Note:**
>
> Contents of my note
>

rendered as {note} confluence macros.

I can write this extension of flexmark-jira-converter and I want to contribute this extension to your project,

But I have several questions before I'll start preparing PR.

1. Are you interesting in such contribution?
2. What's better - to introduce new renderer "CONFLUENCE_WIKI", or extend "JIRA"?
   From one point of view, confluence wiki is extension of JIRA renderer- It render links differently, and have Confluence-specific macros like {info}, {expand}, {toc}, etc
   Form another point of view, JIRA and Confluence are different products by Atlassian Company.
3. What's better:

• Add one extension like flexmark-ext-jira-confluence and write all my stuff in this extension
• Or add 2 extensions flexmark-ext-jira-confluence-admonitions, flexmark-ext-jira-confluence-links

[vsch]

@qwazer, just to make sure we are talking about the same thing.

The flexmark-jira-converter is a markdown to JIRA conversion. It takes the markdown AST as input and renders it as JIRA syntax.

If the confluence wiki conversion is to work on the same principle: markdown to confluence conversion then the same mechanism can be used.

Answers added in between your questions to help track the context:

1. Are you interesting in such contribution?

Absolutely. There are a few user contributions and all are welcome. Even ones with limited use because they can be used as a starting point for someone's custom extension.

2. What's better - to introduce new renderer "CONFLUENCE_WIKI", or extend "JIRA"?
   From one point of view, confluence wiki is extension of JIRA renderer- It render links differently, and have Confluence-specific macros like {info}, {expand}, {toc}, etc
   Form another point of view, JIRA and Confluence are different products by Atlassian Company.

Based on the number of changes, it is probably better to add a CONFLUENCE_WIKI renderer type. For all extensions which have the same rendering in confluence and jira, JIRA custom renderer will be used for both.

For extensions which have a difference in rendering, either a new custom renderer can be added to the extension or the custom rendering can be added to the confluence wiki converter's custom renderer.

My preference would be to add confluence rendering to each affected extension if only to keep code depending on the extension close together but this is not critical if it easier to have all rendering in the confluence wiki extension's custom renderer.

In either case, extensions can add their own custom node render for CONFLUENCE_WIKI without needing to modify the confluence wiki extension. All renderers are extensible using the core renderer mechanism.

I will probably add logic to the API to allow render type inheritance to allow defining CONFLUENCE_WIKI as a subclass of JIRA. This will eliminate any need to change extensions where JIRA can be used for confluence wiki. Effectively, if the exact renderer type is not supported then next available from the inheritance list will be used.

3. What's better:

• Add one extension like flexmark-ext-jira-confluence and write all my stuff in this extension
• Or add 2 extensions flexmark-ext-jira-confluence-admonitions, flexmark-ext-jira-confluence-links

I think implementing one extension is simpler. To allow turning off the confluence admonition rendering you can always add an option to the extension configuration to allow turning this rendering off. This will give you the flexibility of having two separate extensions without the overhead of implementing two extensions or making users add both to the extension list.

[qwazer]

@vsch Thanks for answers!

Yes, we are talking about about the same thing:
take markdown AST as input and render as JIRA/CONFLUENCE_WIKI syntax.

Based on the number of changes, it is probably better to add a CONFLUENCE_WIKI renderer type

Does it mean that it will affect all extensions flexmark-ext-*? At least next code snippets

        if (rendererType.equals("HTML")) {
            rendererBuilder.nodeRendererFactory(new XXXNodeRenderer.Factory());
        } else if (rendererType.equals("JIRA") || rendererType.equals("YOUTRACK")) {
        }

will be replaced by

        if (rendererType.equals("HTML")) {
            rendererBuilder.nodeRendererFactory(new XXXNodeRenderer.Factory());
        } else if (rendererType.equals("JIRA")
                           || rendererType.equals("CONFLUENCE_WIKI")
                           || rendererType.equals("YOUTRACK")) {
        }

I will probably add logic to the API to allow render type inheritance to allow defining CONFLUENCE_WIKI as a subclass of JIRA. This will eliminate any need to change extensions where JIRA can be used for confluence wiki. Effectively, if the exact renderer type is not supported then next available from the inheritance list will be used.

Sound nice. I'm interesting in this feature :)

Anyway, for clear expectations. I cannot promise fast contribution. May be it will take a month or above.

[vsch]

@qwazer, equivalence rendering types added. Very basic but does the job. You can take a look at youtrack for how it is defined so other extensions which render "JIRA" will work with it.

YouTrackConverterExtension.java: Lines 32-42

So if you create an equvalence between your rendering type and "JIRA" all extensions will render JIRA when your rendering type is selected.

Repo updated, maven update in progress.

[qwazer]

@vsch Cool! Thanks for so quick update!

[qwazer]

Thank you @vsch for the library!
Finally I start using it in my project md2conf/md2conf
New converters cannot be contributed back, because these are very specific for general usage.
Example: CrosspageLinkPostProcessor
But you library is extremely helpful.

Thanks you!

[vsch]

You are welcome and don't worry about contributing back, unless it makes sense for a wide audience.

I find that just the fact that the library is used, helps improve its features and stability.