Clojurians Log v2
cljdoc 2024-03-29
Quick question about Latex support! It is currently possible to render Latex in .adoc files via the AsciiDoc STEM support that uses MathJax (thanks @lee! https://github.com/cljdoc/cljdoc/pull/442). But... is it possible to render Latex in Markdown docstrings within a .clj file? For example, I would like to do something like this:
(defn sum-cubes
"\$sum_(i=1)^n i^3=((n(n+1))/2)^2\$"
[n]
(let [sum-to-n (/ (* n (inc n)) 2)]
(* sum-to-n sum-to-n))):stem: attribute), but I wanted to double check before going any further. Thanks!
Hi @eightysteele! There is no fancy math rendering support in docstrings nor .md files. It is only supported for .adoc files.
Hi @lee, thank you for confirming! Would there be any interest in a PR contribution for this?
From a glance it looks like Markdown for docstrings uses flexmark-java under the hood (to render the GitHub flavored CommonMark dialect): https://github.com/cljdoc/cljdoc/blob/master/doc/userguide/for-library-authors.adoc#markup-formats
And then flexmark-java supports the GitLab Flavoured Markdown extension for Latex (via Katex: https://github.com/KaTeX/KaTeX): https://github.com/vsch/flexmark-java/wiki/Extensions#gitlab-flavoured-markdown
That extension has the following options:
- INLINE_MATH_PARSER : enable inline math parser
- RENDER_BLOCK_MATH : enable rendering math fenced code blocks
- INLINE_MATH_CLASS : default "katex", inline math class attribute
- BLOCK_MATH_CLASS : default "katex" block math class attribute
All to say, it seems plausible to build on that to get math rendering support in docstrings working. After adding the extensions to deps.edn, most of the work seems to be updating md-extensions, md-parser-opts, and md-render-opts in render.rich_text.clj. I'm sure that I'm missing a bunch of details here!
Also I haven't thought too hard about what's needed for offline support, but since Katex has zero dependencies and supports server side rendering, it might be relatively painless.
Curious to hear any thoughts. :)
We currently support a subset of GitHub (not GitLab) Flavoured Markdown for docstrings (we don't support embedded HTML in docstrings). But GitHub Markdown https://docs.github.com/en/get-started/writing-on-github/working-with-advanced-formatting/writing-mathematical-expressions, so there's that! My concerns would be: • Once we add a feature, it must be maintained forever. Many folks are happy to add a feature, but not many are willing to stick around for years to maintain it (well, I know of one who can sometimes be willing! simple_smile) • Would some existing docstring contents be misinterpreted as STEM? It seems probably unlikely, but might be worth a think/look. • If we were to add this, it would be nice to use the same tech for all STEM, if that would work. We currently use MathJax for adoc STEM content. I've not looked at KaTeX at all yet. Soo... I dunno. How important is this to you? Do you know of others itching for this feature?