Support admonitions in Markdown docs

[bbatsov]

I typically publish my project's docs using MkDocs () and I'm always making use of https://github.com/Python-Markdown/markdown/blob/master/docs/extensions/admonition.md

Seems that's not currently supported by whatever Markdown processor cljdoc uses, which is quite unfortunate for me.

Take a look here https://cljdoc.xyz/d/nrepl/nrepl/0.4.4/doc/middlewares and you'll immediately understand my problem.

[martinklepsch]

It seems this would be fixable by switching to flexmark-java (based on commonmark-java which we are using currently).

That said admonitions are fairly non-standard Markdown features (i.e. not part of CommonMark or GFM) so maybe in this case it would be better to just use a markup language that supports this (e.g. Asciidoc)?

By doing so you'd also get better rendering support on GitHub as your admonitions aren't rendered correctly there either.

You can mix and match Asciidoc and Markdown with cljdoc as you like, as long as references to other pages are basic links they will be rewritten work properly. (Here's an admonition example from the yada docs.)

[bbatsov]

Yeah, I understand other doc formats might be more flexible, but I had written a lot of Markdown in the past and I'm not exactly excited to have to convert all of it to something else. :-)

By doing so you'd also get better rendering support on GitHub as your admonitions aren't rendered correctly there either.

Generally the doc folders in my projects are supposed to be consumed like this nrepl.readthedocs.org.

Anyways, that's not a big deal, and I can think about trying to convert everything to rst or something like this with pandoc. Maybe the conversion will work better than I expect.

[martinklepsch]

Yeah, I understand other doc formats might be more flexible, but I had written a lot of Markdown in the past and I'm not exactly excited to have to convert all of it to something else. :-)

I totally understand and as I said, we could support this. Contributions certainly welcome but I'm not sure how fast I'll get to it myself.

convert everything to rst or something

.rst is not currently supported (only Markdown & Asciidoc are) but would be great to add that as well.

[bbatsov]

Good to know. rST has the advantage that it's the default format for Sphinx and by association ReadTheDocs.

I'd love to tackle this myself, but looking at my own backlog I just get depressed. 🤣

[martinklepsch]

@bbatsov I looked into Flexmark's admonition support earlier and I think I'd like to avoid getting into this kind of stuff. Icons were not included as described in the documentation, it comes with some 250 lines of CSS and even some JS.

As mentioned before I think in this case it's best to rely on tools that support the desired formatting by default. So would you be open to someone porting the files using admonitions to Asciidoc? While Asciidoc admonitions aren't rendered perfectly yet (#77) I'd feel much better improving that than dealing with somewhat uncommon Markdown extensions.

Here's a list of all files using admonitions:

• https://github.com/nrepl/nREPL/blob/master/doc/design.md
• https://github.com/nrepl/nREPL/blob/master/doc/installation.md
• https://github.com/nrepl/nREPL/blob/master/doc/third_party_middleware.md

It's not that many actually — and Asciidoc and Markdown can be used interchangeably on cljdoc so there's no need to port all of them.

[bbatsov]

I'll think about this. I'm just super busy and changing doc formats is not something I'm willing to spend my time on. I'd still like to publish the manual on nrepl.org as well, but with asciidoc I'll have to look into some different toolchain for gh-pages I presume.

Anyways, feel free to close this ticket.

[martinklepsch]

Maybe @SevereOverfl0w would be interested in helping with this, knowing his appreciation for Asciidoc 🙂

[SevereOverfl0w]

If you don't mind adopting the asciidoctor style (e.g. https://juxt.pro/yada/manual/index.html) then publishing to your own site is as simple as running the asciidoctor cli against your project.

Moving between markdown and asciidoctor isn't too bad, especially as asciidoctor has some support for markdown. I might be convinced to spend an afternoon transferring the docs to asciidoc, if there was a solution you were happy with for nrepl.org.

[bbatsov]

Yeah, I’m fine with that suggestion.

[martinklepsch]

With cider nREPL having moved from markdown to asciidoc I will close this issue for now.

[bbatsov]

nREPL ;-)

P.S. You made an AsciiDoc believer out of me!