Clojurians Log v2

Hi Sean! Cljdoc currently only supports .adoc, .md, and .txt (plaintext). We'd have to think about what supporting .html might mean. The formats we currently support don't include specific styling, so cljdoc can impose its styling aesthetic on them.

Yeah, that's what I suspected and I was wondering about the styling. I guess you could wrap the HTML in an iframe...

I suppose, but cljdoc has a specific and consistent styling. Random HTML would do its own thing. Can you point me to an example of HTML generated by Marginalia? It might give me some ideas of what we might do to support Marginalia-generated content. BTW, I should also gauge interest. Is this just a curiosity, or are you very interested in cljdoc presenting this content?

Marginalia produces a fully self-contained single-page HTML document by default, with text on the left and code on the right. It would be "nice" to be able to incorporate it somehow with the cljdoc-generated docs so projects don't need two different doc sites. I guess a basic question is: If cljdoc finds files in docs/ that aren't *.md or *.adoc (or *.txt), do they end up copied into the appropriate place on http://cljdoc.org or are they completely ignored? What about images, for example?

And then then next Q is: what happens if *.md files include HTML in their bodies? That's just rendered like regular Markdown does it -- inline?

I don't have a Marginalia-generated HTML file anywhere that serves up HTML right now -- only as raw files in GH: https://github.com/clj-commons/marginalia/blob/master/docs/uberdoc.html

> If cljdoc finds files in docs/ that aren't *.md or *.adoc (or *.txt), do they end up copied into the appropriate place on http://cljdoc.org or are they completely ignored? What about images, for example? They won't end up in your doc tree. Relative images are always sourced from your GitHub (or whatever hosted git you use) repo.

Ah, OK. I wasn't sure...

> And then then next Q is: what happens if *.md files include HTML in their bodies? That's just rendered like regular Markdown does it -- inline? Like GitHub, cljdoc supports a limited subset of HTML embedded in .md files.

Ah, I didn't realize it was limited -- I thought it was just passed through when rendering. TIL.

Yeah, GitHub wants to preserve its vanilla look and feel and wants content to be safe too, I guess. So it is conservative in what HTML it lets pass through.

Unlike cljdoc, GitHub does render .html files tho... so I was curious what a Marginalia file looks like rendered by GitHub (plain old repo rendering not GitHub pages).

Hmm, I couldn't figure out how to view that uberdoc.html rendered on the repo...

Oh maybe I'm wrong... I think it supports README.html.... but... I guess I'll have to double check that.

Probably just README...

Oh right... you gave a link above: https://github.com/clj-commons/marginalia/blob/master/docs/uberdoc.html... ya probably just README.html (if that).

Oh that uberdoc.html also has JavaScript...so.. that would be a security concern for cljdoc.

Spitballing... but... would one viable idea be for cljdoc to generate Marginalia docs on request?

I should learn more about Marginalia tho... cljdoc is currently a tool to document public APIs. Does that mesh with Marginalia's typical usage?

Typically, I think folks generate marg-uberdocs from a subset of the namespaces in their project and it's more suitable as articles than an alternative to API docs.

For example, the old Marginalia uberdoc was originally generated from leiningen.marg plus some of the main Marginalia repo nses -- and I haven't figured out a good way to include that ns since it's part of a different repo...

Ah ok. I've cracked open that uberdoc.html in my browser. So geared toward maybe a reader who is interested in not just learning about the API but also the annotated source?

Yeah, it's very much the "literate programming" thing...

Right. Cool.

I used it for one of the apps I developed at work. Started off with all the prose and then gradually implemented some of the prose as code -- and the document was a good working basis for both business and devs to collaborate.

That's why I was thinking of it as an "article" along with other things.

Ya. Hmm... worth thinking about.

Maybe copy *.html in but treat them as opaque docs and have the nav link target="_blank" ?

(assuming cljdoc could serve up static html?)

Dunno... I don't think I'd want cljdoc to deliver unsanitized HTML... even if delivered opaquely.

Not sure yet what the embedded JavaScript does. Can take a deeper peek sometime. Before looking at that sample HTML you shared, I was wondering if we could have marginalia optionally generate to .md or adoc instead. But... I'm guessing making it look nicey nicey might be a bit of a challenge.

(Lurkers please do chime in if you are also interested in Marginalia support in cljdoc.)

point_up::skin-tone-2 That probably needs to go to the channel for anyone else to see it 🙂

Lurkers please do chime in if you are also interested in Marginalia support in cljdoc.

FYI: I just regen'd that uberdoc.html with the leiningen.marg ns in -- via https://github.com/clj-commons/marginalia/blob/master/project.clj#L20-L24

tx!

Interesting, so sometimes you'd create namespaces for doc purposes only, like problem-cases.general.

I gotta go for now, but it seems worth exploring to me, Sean. My initial inclination would be to have cljdoc generate Marginalia docs (or Maginalia equivalent docs), but we'd also want to provide an easy/quick way to preview (and the cljdoc preview story is pretty clunky right now). This is just an initial bias, I'm sure there are other ideas worth exploring.

> Lurkers please do chime in if you are also interested in Marginalia support in cljdoc. Just came across this message from last year while searching for Marginalia support. I'm a lurker and I'm chiming in ;)

Since this came up in the metrics-clojure thread 🙂 Any further thoughts on ways to support HTML or Marginalia in http://cljdoc.org?

I'm still somewhat inclined to push for http://cljdoc.org allowing .html pages to copy into the docs tree and letting maintainers link to them however they want 🙂

(So I could at least add a wrapper in .md that opens the .html in a new window)

there is this old issue https://github.com/cljdoc/cljdoc/issues/433, would it help? means html is hosted elsewhere

Not really. I'm specifically trying to avoid hosting docs elsewhere, so that they can be properly versioned like everything else.

Thanks for chiming in @ramblurr!