Fix text/latex MIME type in LaTeXWriter

CHANGELOG.md

@@ -1,5 +1,8 @@
 # Documenter.jl changelog
 
+## Unreleased
+
+* ![Bugfix][badge-bugfix] Fix text/latex MIME type in LaTeXWriter. ([#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/Writers/LaTeXWriter.jl

@@ -398,7 +398,8 @@ function latex(io::IO, d::Dict{MIME,Any})
         \\end{figure}
         """)
     elseif haskey(d, MIME"text/latex"())
-        latex(io, Utilities.mdparse(d[MIME"text/latex"()]; mode = :single))
+        # If it has a latex MIME, just write it out directly.
+        _print(io, d[MIME"text/latex"()])
     elseif haskey(d, MIME"text/markdown"())
         latex(io, Markdown.parse(d[MIME"text/markdown"()]))
     elseif haskey(d, MIME"text/plain"())

test/examples/src.latex_simple/index.md

@@ -28,3 +28,96 @@ julia> 127 % Int8
 ```julia-repl sayhello2
 julia> function foo end;
 ```
+
+## Issue 1401: rendering custom LaTeX
+
+### @example block / show with `text/latex` MIME
+
+```@example
+struct Table end
+
+Base.show(io, ::MIME"text/latex", ::Table) = write(io, raw"""
+\begin{tabular}{r|ccc}
+        & i & y & z\\
+        \hline
+        & Int64 & Char & Int64\\
+        \hline
+        1 & 1 & 'A' & 5 \\
+        2 & 2 & 'B' & 6 \\
+        3 & 3 & 'C' & 7 \\
+        4 & 4 & 'D' & 8 \\
+\end{tabular}
+""")
+
+Table()
+```
+
+### @raw block
+
+```@raw latex
+\begin{tabular}{r|ccc}
+        & i & y & z\\
+        \hline
+        & Int64 & Char & Int64\\
+        \hline
+        1 & 1 & 'A' & 5 \\
+        2 & 2 & 'B' & 6 \\
+        3 & 3 & 'C' & 7 \\
+        4 & 4 & 'D' & 8 \\
+\end{tabular}
+```
+
+### Inline LaTeX
+
+_Note: this should render as just text, not as a table._
+
+\begin{tabular}{r|ccc}
+        & i & y & z\\
+        \hline
+        & Int64 & Char & Int64\\
+        \hline
+        1 & 1 & 'A' & 5 \\
+        2 & 2 & 'B' & 6 \\
+        3 & 3 & 'C' & 7 \\
+        4 & 4 & 'D' & 8 \\
+\end{tabular}
+
+## 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]
+""")
+```
+
+```@example
+struct LaTeXEquation2
+    content::String
+end
+
+function Base.show(io::IO, ::MIME"text/latex", x::LaTeXEquation2)
+    # Wrap in \[...\] for display math printing
+    return print(io, "\\[ " * x.content * " \\]")
+end
+
+LaTeXEquation2(raw"""
+    \left[\begin{array}{c}
+        x \\
+        y
+    \end{array}\right]
+""")
+```