Heya! I am happily writing up some asciidocs for a project that will eventually end up on cljdocs. I have been using a browser extension (https://github.com/asciidoctor/asciidoctor-browser-extension) to test locally and now am verifying locally with cljdocs itself. I am noticing that some formatting is stronger from the browser plugin. Actually the browser plugin seems to almost match the asciidoctor docs, so I can point there for examples.

One example is the callout formatting. Quite nice from asciidoctor https://asciidoctor.org/docs/user-manual/#callouts, but not nearly as obvious from cljdocs when I am testing locally.

We get the nice strong black numbered circles on asscidoctor and instead text like (1) that does not catch the eye as well from cljdoc.

Also, source code blocks can have a title, this is pretty clear in this example: https://asciidoctor.org/docs/user-manual/#applying-source-highlighting but the title appears, in my testing, as normal text for cljdoc.

Anyway, I am happy to raise illustrative git issues (and fix if you are interested) if you agree that these types of changes are of interest.

Totally of interest 👌🙌

Coolio will doolio!

I’m currently struggling with how to express a root relative link in asciidocs (in general, nothing cljdoc specific here). This would allow me to have a link that automatically works when testing locally with cljdoc and after it was published. My use case is linking from an article to an api. I’d like to say link:/d/clj-commons/rewrite-cljc/CURRENT/api/rewrite-cljc/parse[parse API docs] instead of [parse API docs] Anybody know if this can work in asciidocs?

I’m not sure I fully understand. Would you like to use relative links in the source document?

I was thinking relative from the root (aka domain) would be cleanest, but I don’t think asciidoc can do those. I’ll poke around a bit more.

Oh hmm… I should probably not use root relative because my docs will also be read from github.

Yeah, that’s something I’d like to support if possible - if possible docs should be readable on GitHub/etc. that’s why all the relative link rewriting stuff is in place for articles

Potentially we could rewrite source file links to their respective API docs but there will be other trade offs around that decision

I’m going to happily abandon my little relative link quest for now. Does not seem worth it.