# Equation numbering in Documenter.jl

**URL:** <https://discourse.julialang.org/t/equation-numbering-in-documenter-jl/65349>\
**Category:** Tooling\
**Tags:** documenter\
**Created:** [July 27, 2021, 5:40am UTC](https://discourse.julialang.org/t/equation-numbering-in-documenter-jl/65349 "2021-07-27T05:40:47Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![sbrisard](https://sea2.discourse-cdn.com/julialang/user_avatar/discourse.julialang.org/sbrisard/32/24712_2.png) [@sbrisard](https://discourse.julialang.org/u/sbrisard)\
**Post date:** [July 27, 2021, 5:40am UTC](https://discourse.julialang.org/t/equation-numbering-in-documenter-jl/65349/1 "2021-07-27T05:40:48Z")

</div>

Equation numbering was discussed in [this issue](https://github.com/JuliaDocs/Documenter.jl/issues/975) (see also [this message](https://discourse.julialang.org/t/documenter-jl-how-to-equations-with-label-ref/8742)). The solution proposed above by @mortenpi indeed works with the  
`MathJax3` engine, but not with the… `LaTeXWriter`!

## Description of the problem

The following markdown input

````md
```math
\begin{equation}
  \label{foo}
  E = mc^2
\end{equation}
```

Equation \eqref{foo} means that ...

````

delivers the following LaTeX output

```latex
\begin{equation*}
\begin{split}\begin{equation}
  \label{foo}
  E = mc^2
\end{equation}\end{split}\end{equation*}

Equation {\textbackslash}eqref\{foo\} means that ...

```

The problems are

1. the nested `equation*`/`equation` environments,
2. `\eqref{\foo}` which is automatically replaced with `{\textbackslash}eqref\{foo\}`.

## Fix for problem 1

In function `latex(io::IO, math::Markdown.LaTeX)`, the following regexp

```julia-auto
r"^\\begin\{align\*?\}"

```

should be replaced with

```julia-auto
r"^\\begin\{((equation)|(align)|(gather)|(flalign)|(multline)|(alignat)|(split))\*?\}"

```

Note that the above regexp would accept a `\begin{split*}...\end{split*}` construct, which is not valid LaTeX/AMSMath. In my view, this is not an issue: the `LaTeX` writer is not a parser, and should not be doing the work of the latex engine itself.

I will submit a PR for this minor correction.

## Fix for problem 2

A temporary fix would be to enclose the `\eqref` statement in double  
back-ticks (inline math), like so

````md
```math
\begin{equation}
  \label{foo}
  E = mc^2
\end{equation}
```

Equation ``\eqref{foo}`` means that ...

````

I personally dislike this solution. Clearly, the problem lies with the function `latexesc(io, ch::AbstractChar)`, where `'\\'` gets replaced with `{\\textbackslash}`. Frankly, I hardly see the point of this substitution. This kills the possibility of using LaTeX macros in the markdown file (in case we would be mostly interested in the LaTeX output, for example).

Maybe a more appropriate rule would be

- backslashes occuring outside code blocks (single or triple backticks) → do not perform the substitution,
- backslashes occuring inside code blocks → perform the substitution.

Alternatively, we could look at how [pandoc](https://pandoc.org/) handles such cases.

Any thoughts?