Clojurians Log v2

Thanks @lee, that’s a great summary. Would you prefer the discussion be continued over on Github?

left my reply over on Github, I’ll also start having a looking at the Contributing docs to see if I can take a stab at this this coming week

Yeah, thanks @achan961117, probably best to capture further notes and ideas under https://github.com/cljdoc/cljdoc/issues/20 And @nbtheduke, although I came down on you like a ton of bricks on this topic in the past 😬, I was probably overly negative on the idea itself, you might be interested in chiming in.

we were both sharp, no hard feelings. i've since been using the <!-- toc --> tag with a cli tool to generate the TOCs and that works fine enough. i think i'd continue to use them even if cljdoc added support, as cljdoc isn't the only place to read the documentation (github, local files), but having AWS-style toc would be sick and i would make great use of it in Splint especially

for example: https://cljdoc.org/d/io.github.noahtheduke/splint/1.20.0/doc/rules-overview/style that's a big list at the top. i'd remove it and let cljdoc render it for me, whereas i'd keep the readme toc which is more manageable

Oh good example, thanks for sharing that.

Hiya @achan961117! You mean a table of contents, yes? The PR was rejected because it was too specific, and there was no discussion/agreement at all on how to implement. Issue 20 is still technically open. Are you thinking of a left-side navigation like in the AWS docs example? Would the navigation be integrated into the current article navigation or stand on its own? Any conflict with articles that already have a table of contents? (optionally generating https://cljdoc.org/d/rewrite-clj/rewrite-clj/1.2.50/doc/user-guide, and some folks https://cljdoc.org/d/io.github.noahtheduke/lazytest/1.6.1/doc/readme#table-of-contents). We https://cljdoc.org/d/org.clojure/clojure/1.12.0/doc/readme. They would not be candidates for any table of contents discovery.

Yes a table of contents for the current page! (i.e. all links are anchor links) UI-wise indeed a left-side sticky navigation like AWS is what I’m after (and I’ve since found many similar examples, https://squidfunk.github.io/mkdocs-material/getting-started/, https://scicloj.github.io/docs/resources/libs/, https://docs.asciidoctor.org/asciidoc/latest/’s own docs) For articles that have inlined toc it’d indeed be a bit of duplication. But in practice whenever I’ve come across docs that have these inlined page-toc and have a super long page (i.e. https://cljdoc.org/d/clj-kondo/clj-kondo/2025.01.16/doc/configuration, https://cljdoc.org/d/zprint/zprint/1.2.9/doc/zprint-reference), the inlined toc was only useful for if I know exactly what I needed to lookup (at which point I’m often better served by simply searching the page via browser), whereas for the purpose of browsing/learning the library the inlined-toc does next to nothing because it’s already out of view. And my personal guess for why these library authors makes an inlines page-toc in the first place is because the lack of tooling that generates a sticky TOC in the first place, and I would not be surprised if authors remove these inlined toc in the future if tooling generates a better one (case in point it used to be very common for readmes on Github to have inlined toc, but ever since Github started generating a toc, it’s very rare nowadays to find these toc on readmes) I’m not sure what’s full set of doc formats that cljdoc supports, but I’d say for this feature it can be implemented on a best effort basis, so .txt docs not getting the toc should be fine

Cljdoc supports .md, .adoc, and .txt. So not a huge set of supported doc types! I use .adoc and tend to have it generate tocs. Maybe I'd stop doing that if cljdoc did it? I dunno yet. Some folks read docs on github so I might leave them in? https://github.com/cljdoc/cljdoc/blob/master/doc/userguide/for-library-authors.adoc#asciidoc-environment! The AWS design seems pretty nice to me. For the desktop view, "on this page" stays in place and highlights which section you are on as you scroll through content. And it can be toggled on or off, which is good. For the mobile view, they move "on this page" to a collapsed (by default) header above the content. Seems good to me. They seem to only show level 1 heading items in the toc, which seems reasonable. When there are no level 1 heading items, they omit the "on this page" section.

So it seems like a good generic approach to me, @achan961117. Any cons that you can think of? I suppose garbage-in-garbage-out headings in an article would be one. I suppose we should consider existing secondary navigation in cljdoc and decide if toc should look and behave consistently? For example, var navigation under namespaces https://cljdoc.org/d/rewrite-clj/rewrite-clj/1.2.50/api/rewrite-clj.zip

@achan961117, I took a stab at capturing the above in issue 20: https://github.com/cljdoc/cljdoc/issues/20#issuecomment-2920740152