# Learning to write and rendering Julia-style Markdown

**URL:** <https://discourse.julialang.org/t/learning-to-write-and-rendering-julia-style-markdown/123243>\
**Category:** New to Julia\
**Tags:** documentation, documenterjl\
**Created:** [November 29, 2024, 11:17am UTC](https://discourse.julialang.org/t/learning-to-write-and-rendering-julia-style-markdown/123243 "2024-11-29T11:17:55Z")\
**Posts on this page:** 9\
**Page:** 1

<div class="post-metadata">

**Author:** ![Benny](https://avatars.discourse-cdn.com/v4/letter/b/49beb7/32.png) [@Benny](https://discourse.julialang.org/u/Benny)\
**Post date:** [November 29, 2024, 11:17am UTC](https://discourse.julialang.org/t/learning-to-write-and-rendering-julia-style-markdown/123243/1 "2024-11-29T11:17:55Z")

</div>

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.

---

<div class="post-metadata">

**Author:** ![PetrKryslUCSD](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/petrkryslucsd/32/215825_2.png) [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)\
**Post date:** [December 2, 2024, 5:41pm UTC](https://discourse.julialang.org/t/learning-to-write-and-rendering-julia-style-markdown/123243/3 "2024-12-02T17:41:32Z")

</div>

Agreed, typesetting math in Julia markdown has its quirks:  
 ![image](https://global.discourse-cdn.com/julialang/original/3X/4/2/420670fda03ad93e2dd8ff60e1adfd2a4e9648e4.png)  
The backslash needs to be doubled up. Both in the displayed equation and inline:  
 ![image](https://global.discourse-cdn.com/julialang/original/3X/4/d/4d5c0a9ae9d5ac48fb2c4999846314397feca607.png)  
So it is definitely not possible to just take Latex source and paste it.

---

<div class="post-metadata">

**Author:** ![PetrKryslUCSD](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/petrkryslucsd/32/215825_2.png) [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)\
**Post date:** [December 2, 2024, 5:54pm UTC](https://discourse.julialang.org/t/learning-to-write-and-rendering-julia-style-markdown/123243/4 "2024-12-02T17:54:24Z")

</div>

There is a decent extension for typesetting latex in VS Code. `LaTeX Workshop` can even show hover preview of equations. Pretty neat.

---

<div class="post-metadata">

**Author:** ![Benny](https://avatars.discourse-cdn.com/v4/letter/b/49beb7/32.png) [@Benny](https://discourse.julialang.org/u/Benny)\
**Post date:** [December 2, 2024, 5:56pm UTC](https://discourse.julialang.org/t/learning-to-write-and-rendering-julia-style-markdown/123243/5 "2024-12-02T17:56:03Z")

</div>

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](https://documenter.juliadocs.org/stable/man/latex/). `String` literals however need to escape raw backslashes and `$`, but we get escape sequences and object interpolation in return.

---

<div class="post-metadata">

**Author:** ![PetrKryslUCSD](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/petrkryslucsd/32/215825_2.png) [@PetrKryslUCSD](https://discourse.julialang.org/u/PetrKryslUCSD)\
**Post date:** [December 2, 2024, 5:58pm UTC](https://discourse.julialang.org/t/learning-to-write-and-rendering-julia-style-markdown/123243/6 "2024-12-02T17:58:26Z")

</div>

I really don’t know. What I know is I couldn’t have gotten this

 ![image](https://global.discourse-cdn.com/julialang/original/3X/0/2/02c6c7c3a2640e50c03a7eeb0b60bd42eb350552.png)  
without doubling the backslashes.

---

<div class="post-metadata">

**Author:** ![Benny](https://avatars.discourse-cdn.com/v4/letter/b/49beb7/32.png) [@Benny](https://discourse.julialang.org/u/Benny)\
**Post date:** [December 2, 2024, 5:59pm UTC](https://discourse.julialang.org/t/learning-to-write-and-rendering-julia-style-markdown/123243/7 "2024-12-02T17:59:56Z")

</div>

~~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](https://petrkryslucsd.github.io/FinEtools.jl/latest/man/functions.html#FinEtools.FEMMBaseModule.bilform_convection-Union%7BTuple%7BDC%7D,%20Tuple%7BQT%7D,%20Tuple%7BT%7D,%20Tuple%7BFT%7D,%20Tuple%7BA%7D,%20Tuple%7BFEMM%7D,%20Tuple%7BFEMM,%20A,%20NodalField%7BFT%7D,%20NodalField%7BT%7D,%20NodalField%7BQT%7D,%20DC%7D%7D%20where%20%7BFEMM%3C:AbstractFEMM,%20A%3C:AbstractSysmatAssembler,%20FT,%20T,%20QT,%20DC%3C:DataCache%7D). 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):

```julia
julia> raw"\int_{V} {w} \rho \mathbf{u} \cdot \nabla q \; \mathrm{d} V"
"\\int_{V} {w} \\rho \\mathbf{u} \\cdot \\nabla q \\; \\mathrm{d} V"

```

I should probably find a better way than that though, just lacking an alternative idea than finding and replacing at the moment.

---

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [December 2, 2024, 6:58pm UTC](https://discourse.julialang.org/t/learning-to-write-and-rendering-julia-style-markdown/123243/8 "2024-12-02T18:58:26Z")

</div>

One thing I like to do is to do the formulae – or logical blocks of a doc string as a raw, so for example

````julia
_doc_M = raw"""```math
\mathcal M
```"""

````

to then interpolate them wherever used (to avoid code duplication also in doc strings).

```julia
@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.

---

<div class="post-metadata">

**Author:** ![Benny](https://avatars.discourse-cdn.com/v4/letter/b/49beb7/32.png) [@Benny](https://discourse.julialang.org/u/Benny)\
**Post date:** [December 2, 2024, 7:52pm UTC](https://discourse.julialang.org/t/learning-to-write-and-rendering-julia-style-markdown/123243/9 "2024-12-02T19:52:33Z")

</div>

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
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?

---

<div class="post-metadata">

**Author:** ![kellertuer](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/kellertuer/32/220707_2.png) [@kellertuer](https://discourse.julialang.org/u/kellertuer)\
**Post date:** [December 3, 2024, 6:54am UTC](https://discourse.julialang.org/t/learning-to-write-and-rendering-julia-style-markdown/123243/10 "2024-12-03T06:54:42Z")

</div>

As far as I understand the documentation of [`@doc`](https://docs.julialang.org/en/v1/base/base/#Core.@doc), the macro can (but does not have to) be used.  
I think I personally use it out of habit.