search

asciidoctor / asciidoctor-intellij-plugin

AsciiDoc plugin for products on the IntelliJ platform (IDEA, RubyMine, etc)
https://intellij-asciidoc-plugin.ahus1.de/
Apache License 2.0
355 stars 145 forks source link

Evaluate kramdown-asciidoc (kramdoc) to convert markdown to asciidoctor #257

Open ahus1 opened 5 years ago

ahus1 commented 5 years ago

Read more about kramdown: https://github.com/asciidoctor/kramdown-asciidoc

ahus1 commented 5 years ago

I found that there is a verion of markdown-to-asciidoctor on maven central; moving to this version instead of the snapshot.

mojavelinux commented 5 years ago

I still think kramdown-asciidoc would be a better option. It's much more thorough and has many more tests. I'll also be continually improving it as I work with individuals, projects, and organizations to migrate to AsciiDoc.

ahus1 commented 5 years ago

@bodiam - I opened this issue as I thought the library wasn't released, and the IntelliJ version used a snapshot version of it.

As part of #268 I found that there is a released version on maven central, so I removed the snapshot version. So this is no longer urgent to me.

I would like to hear your thoughts on whether it would be good to migrate here. Thanks!

mojavelinux commented 5 years ago

Btw, if markdown-to-asciidoctor is going to be continued, I'm all in favor of using it in this context. I'm simply pointing out that kramdoc is currently receiving more attention and will likely give the best results for users. That's partly because I think kramdown is a better Markdown parser, so we're already starting from a stronger position.

bodiam commented 5 years ago

I personally don't mind, I think the choice should be based on which converter is the best I think.

Having said that: in which way would kramdown be better, or what's wrong with the current version?

On 8 Jun 2019, at 19:17, Dan Allen notifications@github.com wrote:

Btw, if markdown-to-asciidoctor is going to be continued, I'm all in favor of using it in this context. I'm simply pointing out that kramdoc is currently receiving more attention and will likely give the best results for users. That's partly because I think kramdown is a better Markdown parser, so we're already starting from a stronger position.

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

mojavelinux commented 5 years ago

Hey @bodiam!

Kramdown is one of the most broadly adopted Markdown processors and very closely matches the rules (and quirks) of the GitHub markdown processor. Given that there's such a broad definition of what Markdown is, this is very important.

kramdown-asciidoc started with the test cases from markdown-to-asciidoctor, but then went on to add almost 100% test coverage, 286 tests, and has been used to convert some of the most complex Markdown documents I've ever seen. It's just very battle tested. I worked hard to craft the AsciiDoc so it leverages Asciidoctor to its full extent. There are still gaps, I'm sure, but it has handled everything we've thrown at it so far.

ahus1 commented 5 years ago

I've opened the original issue. After that I learned that markdown-to-asciidoctor is maven central and has artifacts that I can use in the gradle build. Now I'm happy. Turning this into a showdown of two converters feels a bit awkward to me.

I could imagine having both converters in the plugin with a configurable switch. It could help in situation where @mojavelinux supports organisations to switch to Asciidoctor. I assume that kramdown will run on top of the already included jruby environment of Asciidoctor.

@mojavelinux - if you want kramdown as a second converter in the plugin, I would need a Java example how to setup the converter, and some Gradle snippet on how to add the dependencies to the build. The dependencies shouldn't conflict with AsciidoctorJ.

I can support - as time permits - by adding the necessary Swing UI bits to the the IntelliJ configuration dialogue.

mojavelinux commented 5 years ago

Thanks Alex!

I don't think this is really a showdown. I'm just pointing out that kramdown-asciidoc is being actively developed. If markdown-to-asciidoctor is too, that's great. If it's not, then users are going to start to complain that certain edge cases aren't being converted (or not converted correctly), and I don't want that to fall on your shoulders (and since I've been in that situation many times, I know what it's like).

You're correct that invoking kramdown-asciidoc is a bit extra work since it doesn't provide a Java interface like Asciidoctor. Perhaps that would be a prerequisite for including it in this plugin. Therefore, for that reason alone, the evaluation might be "not yet".

bodiam commented 5 years ago

There are zero reported bugs on the asciidoctor converter library, and it has been successfully used to convert all of the Spring documentation and Geb documentation.

If there are bug reports, more than happy to look into them, though by no means would I claim it's flawless. But it is pretty decent for most scenarios.

Personally, I'd rather get rid of anything JRuby related. The 25 MB runtime binary is a pain for library development, especially compared to a 50 kb library.

On 11 Jun 2019, at 13:29, Dan Allen notifications@github.com wrote:

Thanks Alex!

I don't think this is really a showdown. I'm just pointing out that kramdown-asciidoc is being actively developed. If markdown-to-asciidoctor is too, that's great. If it's not, then users are going to start to complain that certain edge cases aren't being converted (or not converted correctly), and I don't want that to fall on your shoulders (and since I've been in that situation many times, I know what it's like).

You're correct that invoking kramdown-asciidoc is a bit extra work since it doesn't provide a Java interface like Asciidoctor. Perhaps that would be a prerequisite for including it in this plugin. Therefore, for that reason alone, the evaluation might be "not yet".

— You are receiving this because you were mentioned. Reply to this email directly, view it on GitHub, or mute the thread.

ahus1 commented 2 years ago

I'm reopening this, as there is a long-outstanding issue https://github.com/bodiam/markdown-to-asciidoc/issues/32. I also needed to update the transitive dependency parboiled-java to 1.4.1 to support the new JDK17 runtime in #1101.

I see that https://github.com/sirthias/pegdown is no longer maintained.

So I wonder if I should bundle kramdown-asciidoc or use pandoc. For the recently added DOCX conversion (#1074), there is now a on-demand download for pandoc.

To bundle kramdown and to call it from Java, I would need some guidance, therefore I mark it as "help wanted".

bodiam commented 2 years ago

@ahus1 sorry, didn't know about those issues in the converter. I can have an attempt at fixing them, would that solve the issue for you?

bodiam commented 2 years ago

It seems I lost likely will have to rewrite the whole library, since pegdown is no longer maintained, which is the library mine depends on. While that doesn't sound that hard, it's not a need I have at the moment, and it's unlikely I'll find the time to work on this.

ahus1 commented 2 years ago

@bodiam - thanks for commenting here. Fixing https://github.com/bodiam/markdown-to-asciidoc/issues/32 would be a great help, and would remove any urgent need for me to look for something different.

It would also help if you could comment on my attempt here 4445ea460a3d72813b9a37e7bf3dfb88352c7cc8 to update parboiled-java:1.4.1: it seems to do the trick to make it JDK 17 compatible, still you as the maintainer might have different tests to show if this is really working as expected.

Thanks!