Fix escaping of dollar symbols in HTMLWriter (#1625)

Previously, Javascript LaTeX engines got confused trying to
distinguish between inline delimiters and dollar symbols for actual
currency. This works around the problem by wrapping (currency) dollar
symbols in a span tag.

CHANGELOG.md

@@ -1,10 +1,11 @@
 # Documenter.jl changelog
 
-
 ## Version `v0.27.4`
 
 * ![Feature][badge-feature] `@example`- and `@repl`-blocks now support colored output by mapping ANSI escape sequences to HTML. This requires Julia >= 1.6 and passing `ansicolor=true` to `Documenter.HTML` (e.g. `makedocs(format=Documenter.HTML(ansicolor=true, ...), ...)`). In Documenter 0.28.0 this will be the default so to (preemptively) opt-out pass `ansicolor=false`. ([#1441][github-1441])
 
+* ![Bugfix][badge-bugfix] Dollar signs in the HTML output no longer get accidentally misinterpreted as math delimiters in the browser. ([#890](github-890), [#1625](github-1625))
+
 ## Version `v0.27.3`
 
 * ![Feature][badge-feature] Documenter can now deploy documentation directly to the "root" instead of versioned folders. ([#1615][github-1615], [#1616][github-1616])
@@ -643,6 +644,7 @@
 [github-879]: https://github.com/JuliaDocs/Documenter.jl/pull/879
 [github-885]: https://github.com/JuliaDocs/Documenter.jl/pull/885
 [github-886]: https://github.com/JuliaDocs/Documenter.jl/pull/886
+[github-890]: https://github.com/JuliaDocs/Documenter.jl/issues/890
 [github-891]: https://github.com/JuliaDocs/Documenter.jl/pull/891
 [github-898]: https://github.com/JuliaDocs/Documenter.jl/pull/898
 [github-905]: https://github.com/JuliaDocs/Documenter.jl/pull/905
@@ -849,6 +851,7 @@
 [github-1615]: https://github.com/JuliaDocs/Documenter.jl/issues/1615
 [github-1616]: https://github.com/JuliaDocs/Documenter.jl/pull/1616
 [github-1617]: https://github.com/JuliaDocs/Documenter.jl/pull/1617
+[github-1625]: https://github.com/JuliaDocs/Documenter.jl/pull/1625
 
 [julia-38079]: https://github.com/JuliaLang/julia/issues/38079
 [julia-39841]: https://github.com/JuliaLang/julia/pull/39841

src/Writers/HTMLWriter.jl

@@ -1676,7 +1676,17 @@ The `parent` argument is passed to allow for context-dependant conversions.
 """
 mdconvert(md; kwargs...) = mdconvert(md, md; kwargs...)
 
-mdconvert(text::AbstractString, parent; kwargs...) = DOM.Node(text)
+function mdconvert(text::AbstractString, parent; kwargs...)
+    # Javascript LaTeX engines have a hard time dealing with `$` floating around
+    # because they use them as in-line escapes. You can try a few different
+    # solutions that don't work (e.g., HTML symbols $). The easiest (if
+    # hacky) solution is to wrap dollar signs in a <span>. For now, only do this
+    # when the text coming in is a singleton escaped $ sign.
+    if text == "\$"
+        return Tag(:span)("\$")
+    end
+    return DOM.Node(text)
+end
 
 mdconvert(vec::Vector, parent; kwargs...) = [mdconvert(x, parent; kwargs...) for x in vec]
 

test/examples/src/index.md

@@ -501,3 +501,8 @@ MarkdownOnly("""
 ```1392-test-language 1392-extra-info
 julia> function foo end;
 ```
+
+# Issue 890
+
+I will pay \$1 if $x^2$ is displayed correctly. People may also write \$s or
+even money bag\$\$.

test/examples/tests.jl

@@ -43,6 +43,10 @@ end
             @test occursin("documenter-example-output", index_html)
             @test occursin("1392-test-language", index_html)
             @test !occursin("1392-extra-info", index_html)
+            @test occursin(
+                raw"<p>I will pay <span>$</span>1 if <span>$x^2$</span> is displayed correctly. People may also write <span>$</span>s or even money bag<span>$</span><span>$</span>.</p>",
+                index_html,
+            )
 
             example_output_html = read(joinpath(build_dir, "example-output", "index.html"), String)
             @test occursin("documenter-example-output", example_output_html)

test/htmlwriter.jl

@@ -171,5 +171,10 @@ end
             end
         end
     end
+
+    @testset "Dollar escapes" begin
+        @test string(HTMLWriter.mdconvert("\$1")) == "\$1"
+        @test string(HTMLWriter.mdconvert("\$")) == "<span>\$</span>"
+    end
 end
 end