Getting around to learning how to write documentation more sophisticated than ASCII docstrings, so I’m practicing Markdown. VS Code already previews/renders Markdown files with LaTeX equation support, so that’s cool. Thing is, I notice that’s a discrepancy in Julia’s Markdown where LaTeX equations use double backticks or fenced math blocks, Documenter.jl mentioning that the usual $ and $$ are deprecated (I assume it’s because of $-interpolation in string literals). VS Code doesn’t render LaTeX in double backticks out the box, and I haven’t ruled out other discrepancies.
So, how can I make VS Code render Markdown files in Julia’s style? Or are markdown files written in other styles and Julia’s style is just for Julia source code? Any other tips for a Markdown novice? I’d also be interested in a graphical equation builder that generates LaTeX as a learning tool while I’m still unfamiliar.
EDIT 1: Julia’s documentation on its Markdown library and Documenter’s documentation of LaTeX support both use Julia-style Markdown, so Github’s preview only renders LaTeX in fenced math blocks.
EDIT 2: At this point I’m fairly certain there isn’t an actively maintained VS Code extension for this, mdmath is the closest I’ve found this whole time. It’s not like Markdown itself has a consensus standard, but there’s quite a lot of variety and redundancies in how LaTeX is delimited, and more symbols risk clashing with other syntax (rooted in TeX but somewhat deprecated in LaTeX, $ interpolates in many languages’ strings). It’d be nice if fenced code blocks with context identifiers had a widely used inline version, but those are still just a couple implementations among dozens.
Agreed, typesetting math in Julia markdown has its quirks:
The backslash needs to be doubled up. Both in the displayed equation and inline:
So it is definitely not possible to just take Latex source and paste it.
I’m fairly new to this so correct me where I’m wrong, but the raw text of some documentation files suggest we can. Julia-style Markdown files don’t need extra backslash escaping, and nonstandard string literals in source files only need extra backslash escaping for the string’s quotes, so pasting LaTeX is feasible there. String literals however need to escape raw backslashes and $, but we get escape sequences and object interpolation in return.
Is it possible to link to the page or md file so I can reach and look at the raw text? Never mind, found it by googling the first line. Functions · FinEtools.jl. Not positive, but squinting at the docstring it looks like you don’t interpolate anything and don’t need escaping other than LaTeX backslashes, so you might be able to get away with @doc raw"""...""" like Documenter.jl suggested.
Also noticing this display quirk might be useful for adding those extra escape backslashes (and print to remove them):
One thing I like to do is to do the formulae – or logical blocks of a doc string as a raw, so for example
_doc_M = raw"""```math
\mathcal M
```"""
to then interpolate them wherever used (to avoid code duplication also in doc strings).
@doc """
my_fun(M)
where
$(_doc_M)
"""
function my_fun end
That way the @doc string can easily combined.
Besides the string-quirks, you would write quite normal Markdown. the block ```math is quite common,
the inline math with two backticks is the one exception I know, and of course [A](@ref) links within the docs – but at least they follow the usual link syntax.
Oh that’s nice, instantiating the math’s raw string separately lets me interpolate in the main docstring again. It doesn’t even look like I have to really write it separately, though this looks a tad cursed:
julia> """
my_fun(M)
where
$(raw"""
```math
\mathcal M
```
"""
)
"""
" my_fun(M)\n \n where \n```math\n\\mathcal M\n```\n\n"
Is the @doc call necessary in that function block example though, should work without it, right?
