Fix multiline display equations in LaTeX

This is an identical bugfix fo JuliaDocs#1518, which was only applied to the
HTML writer.

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Documenter.jl changelog
 
+## Unreleased
+
+* ![Bugfix][badge-bugfix] Fix multiline display equations in LaTex writer. ([#1709][github-1709])
 
 ## Version `v0.27.8`
 

docs/src/man/latex.md

@@ -115,3 +115,25 @@ To write a system of equations, use the `aligned` environment:
 ```
 
 These are Maxwell's equations.
+
+## Printing LaTeX from Julia
+
+To pretty-print LaTeX from Julia, overload `Base.show` for the
+`MIME"text/latex"` type. For example:
+```@example
+struct LaTeXEquation
+    content::String
+end
+
+function Base.show(io::IO, ::MIME"text/latex", x::LaTeXEquation)
+    # Wrap in $$ for display math printing
+    return print(io, "\$\$ " * x.content * " \$\$")
+end
+
+LaTeXEquation(raw"""
+    \left[\begin{array}{c}
+        x \\
+        y
+    \end{array}\right]
+""")
+```

src/Utilities/Utilities.jl

@@ -629,6 +629,17 @@ The `mode` keyword argument can be one of the following:
 """
 function mdparse(s::AbstractString; mode=:single)
     mode in [:single, :blocks, :span] || throw(ArgumentError("Invalid mode keyword $(mode)"))
+    # If `s` is already wrapped in `\[ ... \]` or `\$\$ ... \$\$``, we unwrap it
+    # and return a Markdown.LaTeX object instead. This is often the case if
+    # users implement a MIME"text/latex" mode to display objects in display math
+    # mode.
+    # Make sure to match multiline strings!
+    m_bracket = match(r"\s*\\\[(.*)\\\]\s*"s, s)
+    m_dollars = match(r"\s*\$\$(.*)\$\$\s*"s, s)
+    if mode == :single && (m_bracket !== nothing || m_dollars !== nothing)
+        out = m_bracket !== nothing ? m_bracket[1] : m_dollars[1]
+        return Markdown.LaTeX(out)
+    end
     md = Markdown.parse(s)
     if mode == :blocks
         md.content

src/Writers/HTMLWriter.jl

@@ -2008,18 +2008,7 @@ function mdconvert(d::Dict{MIME,Any}, parent; kwargs...)
     elseif haskey(d, MIME"image/jpeg"())
         out = Documents.RawHTML(string("<img src=\"data:image/jpeg;base64,", d[MIME"image/jpeg"()], "\" />"))
     elseif haskey(d, MIME"text/latex"())
-        # If the show(io, ::MIME"text/latex", x) output is already wrapped in \[ ... \] or $$ ... $$, we
-        # unwrap it first, since when we output Markdown.LaTeX objects we put the correct
-        # delimiters around it anyway.
-        latex = d[MIME"text/latex"()]
-        # Make sure to match multiline strings!
-        m_bracket = match(r"\s*\\\[(.*)\\\]\s*"s, latex)
-        m_dollars = match(r"\s*\$\$(.*)\$\$\s*"s, latex)
-        if m_bracket === nothing && m_dollars === nothing
-            out = Utilities.mdparse(latex; mode = :single)
-        else
-            out = Markdown.LaTeX(m_bracket !== nothing ? m_bracket[1] : m_dollars[1])
-        end
+        out = Utilities.mdparse(d[MIME"text/latex"()]; mode = :single)
     elseif haskey(d, MIME"text/markdown"())
         out = Markdown.parse(d[MIME"text/markdown"()])
     elseif haskey(d, MIME"text/plain"())