Don’t know why I’m just thinking of this now but custom views in docs would be huge

I think yes if you could specify custom JS , and have cljdoc load the clerk generated HTML

I’m thinking more of something where we do the clerk build for you

Similar to https://github.clerk.garden/ ?

Yeah pretty much.

But like integrated with the docs of a project

yeah I really appreciate the cljdoc global table of contents; also the [[some.ns/var]] resolution for docs is fantastic and I use it all over. I hope Clerk meets cljdoc and supports all of that too

So maybe more likely that clerk might support generating and rendering API docs than cljdoc might supporting rendering of clerk notebooks?

Clerk could do that but also clerk is not aimed at just library documentation. It’s more of a general notebook thing right? And then there’s the build/setup process that is still needed & that cljdoc could automate.

hey 👋

build should be just calling a function and for setup garden uses a convention with deps.edn

cljdoc + clerk integration is also something I thought about in this thread https://clojurians.slack.com/archives/C8V0BQ0M6/p1672950373231089?thread_ts=1672921846.981459&cid=C8V0BQ0M6

maybe cljdoc could also produce a static build that works with a deps.edn project so you don’t need a jar or a server to generate the docs

Currently cljdoc’s TOC supports markdown and .adoc — would be amazing if it were to support Clerk notebooks as entries in the TOC (along markdown or adoc).

there might be some security considerations to think about as well. it seems like cljdocs run under the same domain as http://cljdoc.org. I'm not sure if there are logins or similar associated with http://cljdoc.org, but if producing a clerk static site allowed arbitrary javascript, then extra precautions may be necessary.

what would cljdoc need from clerk for this?

And yes, I’m thinking cljdoc could run a clerk build and store the resulting assets somewhere. To integrate it seamlessly we’d probably want a bit of extra control of HTML/styling just so it visually “fits in”

yep, that’s true @U7RJTCH6J. Would probably need to run in a sandboxed iframe as custom viewers can execute js.

oh, is there even a login that needs to be protected?

I'm not sure.

although, it's probably still good practice to explicitly separate pages that might execute arbitrary javascript from primary domains since it can have negative security consequences for any future feature that assumes otherwise.

There’s no logins on cljdoc

anything else that’s stored in a session / cookie / localstorage? history of accessed libs maybe?

Yes, there’s some very basic stuff like recently visited lobs stored - but I think it’s pretty low risk and the idea of a framework towards interactive docs feels worth that risk

@U050TNB9F, what we would not want is user-provided JavaScript running willy-nilly. Like @U5H74UNSF and @U7RJTCH6J are saying, we'd have to be very careful here.

Sorry, I did not want to throw cold water on your idea @U050TNB9F. What were you imagining? Clerk notebooks rendered by cljdoc, much like .adoc and .md articles are today?

No worries!

I think I’m a little less concerned about security 😇

And yes, basically thinking cljdoc could pick up clerk notebooks and integrate them like md/adoc. Cljdoc could handle the build and hosting as long as projects follow convention and/or provide necessary configuration.

In my mind the security risks are somehow not as big as the upside of interactive docs. Sure it’s not perfect but there is close to 0 private information on cljdoc so I think we could consider making different tradeoffs than what is usually considered acceptable.

Clerk seems to solve a lot of the „standardization“ needs for this kind of thing.

Yeah, I worked pretty hard to sanitize cljdoc HTML. There was a time when anybody could put any JavaScript in their md and adoc and it would just pass-thru and run. I think we could figure out something for clerk notebooks. And if @U5H74UNSF is giving the 😻, well we know we have his blessing!

At one point consistency of presentation (styling) was an important goal for cljdoc. Do you feel this comes into play for clerk notebooks too? Is it achievable?

I think visual consistency is still important. We’d probably want to use existing styles for headings, paragraphs, lists, code blocks etc. Not sure how easy it is to override defaults there but should be possible right?

If I understand correctly, clerk gives complete styling control via tailwind. So imposing a cljdoc look and feel might be tricky? Dunno.

yeah, Clerk’s styling is based on tailwind. Can also customize the markup using custom viewers but that can be quite a bit of work, depending on how deep you want to go.