Replace pegdown with a maintained library

[marcospereira]

Pegdown is not being maintained anymore and has reached EOL:

https://github.com/sirthias/pegdown/#-deprecation-note-

The suggested alternative is flexmark-java which has a documented migration path.

[dwijnand]

Let's replace play-doc instead!

[mkurz]

I think this is still relevant. I don't know who will ever remove play-docs, given that not so many Lightbend employees working on Play anymore...
See playframework/playframework#10819, where I try to make Play work with Java 16/17 and pegdown causing problems...

The suggested alternative is flexmark-java which has a documented migration path.

That sounds promising.

[mkurz]

Migrating away from Pegdown will become necessary at some point.
That is because the parboiled version it is using depends on an old ASM version, which, as it seems, is incompatible with newer ASM versions. That caused problems when I wanted to upgrade sbt-assembly to the latest version in the Play documentation, which pulls in a newer ASM version via its jarjar dependency. For now, we can just keep the old sbt-assembly version in the Play docs, because it's just used to show an example.
However there is different problem already when I worked on Java 17 support for Play: It is not possible anymore to run the validateJobs task anymore on Java 17 because of the old ASM version of pegdown/parboiled as well. Again, this isn't really urgent right now, since we will keep building and validating Play with Java 8 and later with Java 11, but at some point in the future Play will be build with Java 17.

I invested a bit time to see if the migration could be done immediately, turns out its doable, but I don't have enough time right now. Here are some pointers:

• Migration helper: https://github.com/vsch/flexmark-java#pegdown-migration-helper
• Sample of a CustomLinkResolver: https://github.com/vsch/flexmark-java/blob/0.62.2/flexmark-java-samples/src/com/vladsch/flexmark/java/samples/PegdownCustomLinkResolverOptions.java
• More samples that might be usable for migration:
  • https://github.com/vsch/flexmark-java/blob/0.62.2/flexmark-java-samples/src/com/vladsch/flexmark/java/samples/DocxConverterPegdown.java
  • https://github.com/vsch/flexmark-java/blob/0.62.2/flexmark-java-samples/src/com/vladsch/flexmark/java/samples/PegdownToCommonMark.java
• Wiki pages useful for migration:
  • https://github.com/vsch/flexmark-java/wiki/Pegdown-Migration
  • https://github.com/vsch/flexmark-java/wiki/Writing-Extensions
• IMHO looking at how the YouTubeLinkExtension might be useful:
  • https://github.com/vsch/flexmark-java/blob/0.62.2/flexmark-ext-youtube-embedded/src/main/java/com/vladsch/flexmark/ext/youtube/embedded/YouTubeLinkExtension.java
  • https://github.com/vsch/flexmark-java/blob/0.62.2/flexmark-ext-youtube-embedded/src/main/java/com/vladsch/flexmark/ext/youtube/embedded/internal/YouTubeLinkNodePostProcessor.java
  • https://github.com/vsch/flexmark-java/blob/0.62.2/flexmark-ext-youtube-embedded/src/main/java/com/vladsch/flexmark/ext/youtube/embedded/internal/YouTubeLinkNodeRenderer.java
  • https://github.com/vsch/flexmark-java/tree/0.62.2/flexmark-ext-youtube-embedded/src/main/java/com/vladsch/flexmark/ext/youtube/embedded
• Also see LinkRefProcessor / LinkNodeBase and its subclasses
• This conversation might also help: pegdown markdownToHtml and LinkRenderer class replacement in flexmark java  vsch/flexmark-java#105

[mkurz]

It seems we are lucky and can explicitely upgrade parboiled and the old pegdown version will still work, so that buys us time until we find a solution: #155