On Markdown in Java documentation comments

Re:On Markdown in Java documentation comments by prpl on Tuesday January 24, 2023 @12:58PM (#34507328)

Hopefully there’s some overlap with MyST - the markdown format from sphinx. That format is mostly reasonable in terms of extending markdown by enabling sphinx/reST directives.

[ Parent | on HN ]

Re:On Markdown in Java documentation comments by zdw on Tuesday January 24, 2023 @01:51PM (#34508175)

The MyST flavor of markdown is not the same as GitHub flavor, especially about embedding highlighted/replaced content.

If you want an example of this breakage, try embedding a Mermaid format diagram in both of them.

[ Parent | on HN ]

Re:On Markdown in Java documentation comments by prpl on Wednesday January 25, 2023 @02:06AM (#34515306)

I’m well aware. It’s also a one line change to the myst parser to make that work.

In any case, it’s because a myst code block with curly brackets is really a sphinx directive.

That said, they should support the non-directive version, similar to GFM, but would need to embed it. Compared to GFM, though, a plug-in can be added to support plantUML and there’s even crusty ones for graphviz.

GFM version is also not particularly flexible for large diagrams

[ Parent | on HN ]