Fork me on GitHub
Shantanu Kumar09:09:04

Hi, does cljdoc pick up (i.e. consider documentation) EDN files in the doc directory of projects?


Not really. What would you like to see being done with EDN files?

Shantanu Kumar10:09:55

@U050TNB9F These are sample EDN files for annotated reference. I can create markdown files out of them, but that’s manual work.


I see. So right now you’d need to wrap them in Markdown or Asciidoc. I’d be open to a contribution in the direction of allowing people to point to EDN files as articles though


You might be able to include them from asciidoc.


If I remember correctly, cljdoc does not support asciidoc includes... maybe due to some default safety settings... can have a look if there is real interest.


Ah, there'd be a bit of investigation to look at the tools available for protecting from include:/etc/passwd


Ah yeah… that makes sense.


Might be fine given that we literally execute clojure code anyway


We don’t do that for this part of the process, only for the actual source analysis. The ingestion of articles happens on the cljdoc server


Ah, in that case, need to be more careful :)

Shantanu Kumar15:10:33

FWIW I ended up linking to the EDN files from a markdown doc that is rendered by cljdoc, because Github renders EDN decently too.


A question… cljdoc only work from docstrings. Is there a reason why we don’t support wikilinks from articles? (for AsciiDoctor we’d have to use a different syntax, but it is possible).


Do you mean to link to namespaces/vars?


These links wouldn’t work on GitHub etc. and linking already is possible/practical with using CURRENT as version


So I think my main argument against this would be that it creates a poor experience on other platforms with only a mild improvement in the authoring experience


Fair enough. Tx!