Fork me on GitHub
#cljdoc
<
2020-09-08
>
jeremys21:09:37

Hello, Is there a way in articles to link vars similarly to what is possible in docstrings?

seancorfield21:09:39

@jeremys Yes, a link like https://cljdoc.org/d/seancorfield/next.jdbc/CURRENT/api/next.jdbc#get-datasource (from Getting Started) will take the reader direct to that function in the API.

seancorfield21:09:31

The source of that article has

You can see the full list of `:dbtype` values supported in [next.jdbc/get-datasource]( docstring.

jeremys21:09:45

@seancorfield Ok so you create the url yourself, no wikilink magic like in docstings. However the 'CURRENT' part of the url is plenty magic since it seems to resolve to whatever version of the docs you are currently consulting. That's pretty cool. Thanks a lot.

seancorfield21:09:46

The main reason I use the full URL is because otherwise someone browsing the markdown docs in the GitHub repo would not be able to click on those links.

jeremys21:09:12

oh right, I didn't think of that!

seancorfield21:09:45

I've had plenty of confused feedback from users who were reading the doc folder markdown files directly on GitHub 🙂

seancorfield21:09:51

And of course, what's on GitHub is the "latest" code and may not have a release yet -- so that's a case where you can't provide a working link from an article to a newly-added function (since the API docs wouldn't have been generated yet). So that's been a constant battle to try to clarify...

jeremys21:09:38

True! Still, the CURRENT trick in the url allows the articles and the API docs to be in sync which is pretty neat already.

jeremys21:09:49

Another funny problem I am having. When you want to propose deps coordinates for a project using a git sha. You can't have this sha in the version of the readme cljdoc will use. In effect the readme seen on the clj doc's page is one commit behind...

jeremys22:09:44

@seancorfield Thanks again for the url scheme, the docs I generate now link even from intellij's markdown viewer...

seancorfield22:09:29

Re: Git SHA: yeah, you end up needing to do an extra commit where you update just the references to any old SHAs with the latest SHAs.

seancorfield22:09:50

(so the README essentially always needs to be one commit ahead of the code)