WIP

JuliaDocs · Jul 15, 2020 · b63cbe6 · b63cbe6
1 parent 92fb49b
commit b63cbe6
Show file tree

Hide file tree

Showing 4 changed files with 86 additions and 29 deletions.
diff --git a/Project.toml b/Project.toml
@@ -6,6 +6,7 @@ version = "0.25.0"
 Base64 = "2a0f44e3-6c83-55bd-87e4-b1978d98bd5f"
 Dates = "ade2ca70-3891-5945-98fb-dc099432e06a"
 DocStringExtensions = "ffbed154-4ef7-542d-bbb7-c09d3a79fcae"
+DocumenterMarkdown = "997ab1e6-3595-5248-9280-8efb232c3433"
 InteractiveUtils = "b77e0a4c-d291-57a0-90e8-8db25a27a240"
 JSON = "682c06a0-de6a-54ab-a142-c8b1cf79cde6"
 LibGit2 = "76f85450-5226-5b5a-8eaa-529ad045b433"

diff --git a/src/Documenter.jl b/src/Documenter.jl
@@ -51,11 +51,11 @@ include("Deps.jl")
 
 import .Utilities: Selectors
 import .Writers.HTMLWriter: HTML, asset
-import .Writers.HTMLWriter.RD: KaTeX, MathJax
+import .Writers.HTMLWriter.RD: KaTeX, MathJax, MathJax3
 
 # User Interface.
 # ---------------
-export Deps, makedocs, deploydocs, hide, doctest, DocMeta, KaTeX, MathJax, asset
+export Deps, makedocs, deploydocs, hide, doctest, DocMeta, KaTeX, MathJax, MathJax3, asset
 
 """
     makedocs(

diff --git a/src/Writers/HTMLWriter.jl b/src/Writers/HTMLWriter.jl
@@ -192,30 +192,71 @@ struct MathJax <: MathEngine
     config :: Dict{Symbol,Any}
     function MathJax(config::Union{Dict,Nothing} = nothing, override=false)
         default = Dict(
-           :tex2jax => Dict(
-               "inlineMath" => [["\$","\$"], ["\\(","\\)"]],
-               "processEscapes" => true
-           ),
-           :config => ["MMLorHTML.js"],
-           :jax => [
-               "input/TeX",
-               "output/HTML-CSS",
-               "output/NativeMML"
-           ],
-           :extensions => [
-               "MathMenu.js",
-               "MathZoom.js",
-               "TeX/AMSmath.js",
-               "TeX/AMSsymbols.js",
-               "TeX/autobold.js",
-               "TeX/autoload-all.js"
-           ],
-           :TeX => Dict(:equationNumbers => Dict(:autoNumber => "AMS"))
+            :tex2jax => Dict(
+                "inlineMath" => [["\$","\$"], ["\\(","\\)"]],
+                "processEscapes" => true
+            ),
+            :config => ["MMLorHTML.js"],
+            :jax => [
+                "input/TeX",
+                "output/HTML-CSS",
+                "output/NativeMML"
+            ],
+            :extensions => [
+                "MathMenu.js",
+                "MathZoom.js",
+                "TeX/AMSmath.js",
+                "TeX/AMSsymbols.js",
+                "TeX/autobold.js",
+                "TeX/autoload-all.js"
+            ],
+            :TeX => Dict(:equationNumbers => Dict(:autoNumber => "AMS"))
         )
         new((config === nothing) ? default : override ? config : merge(default, config))
     end
 end
 
+_merge(a, b) = b
+_merge(a::Dict, b::Dict) = merge(_merge, a, b)
+_merge(a::Vector, b::Vector) = [a; b]
+
+"""
+    MathJax3(config::Dict = <default>, override = false)
+
+An instance of the `MathJax` type can be passed to [`HTML`](@ref) via the `mathengine`
+keyword to specify that the [MathJax rendering engine](https://www.mathjax.org/) should be
+used in the HTML output to render mathematical expressions.
+
+A dictionary can be passed via the `config` argument to configure MathJax. It gets passed to
+the [`MathJax.Hub.Config`](https://docs.mathjax.org/en/latest/options/) function. By
+default, Documenter set custom configuration for `tex2jax`, `config`, `jax`, `extensions`
+and `Tex`.
+
+By default, the user-provided dictionary gets _merged_ with the default dictionary (i.e. the
+resulting configuration dictionary will contain the values from both dictionaries, but e.g.
+setting your own `tex2jax` value will override the default). This can be overridden by
+setting `override` to `true`, in which case the default values are ignored and only the
+user-provided dictionary is used.
+"""
+struct MathJax3 <: MathEngine
+    config :: Dict{Symbol,Any}
+    function MathJax3(config::Union{Dict,Nothing} = nothing, override=false)
+        default = Dict(
+            :tex => Dict(
+                "inlineMath" => [["\$","\$"], ["\\(","\\)"]],
+                "processEscapes" => true,
+                "tags" => "ams",
+                "packages" => ["base", "ams", "autoload"],
+            ),
+            :options => Dict(
+                "ignoreHtmlClass" => "tex2jax_ignore",
+                "processHtmlClass" => "tex2jax_process",
+            )
+        )
+        new((config === nothing) ? default : override ? config : _merge(default, config))
+    end
+end
+
 """
     HTML(kwargs...)
 
@@ -370,7 +411,7 @@ end
 module RD
     using JSON
     using ....Utilities.JSDependencies: RemoteLibrary, Snippet, RequireJS, jsescape, json_jsescape
-    using ..HTMLWriter: KaTeX, MathJax
+    using ..HTMLWriter: KaTeX, MathJax, MathJax3
 
     const requirejs_cdn = "https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.6/require.min.js"
     const google_fonts = "https://fonts.googleapis.com/css?family=Lato|Roboto+Mono"
@@ -464,6 +505,17 @@ module RD
             """
         ))
     end
+    function mathengine!(r::RequireJS, engine::MathJax3)
+        push!(r, RemoteLibrary(
+            "mathjax3",
+            "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-svg.js",
+        ))
+        push!(r, Snippet(["mathjax3"], ["MathJax"],
+            """
+            window.MathJax = $(json_jsescape(engine.config, 2))
+            """
+        ))
+    end
     mathengine(::RequireJS, ::Nothing) = nothing
 end
 

diff --git a/test/examples/make.jl b/test/examples/make.jl
@@ -187,13 +187,17 @@ examples_html_doc = if "html" in EXAMPLE_BUILDS
                 ],
                 prettyurls = true,
                 canonical = "https://example.com/stable",
-                mathengine = MathJax(Dict(:TeX => Dict(
-                    :equationNumbers => Dict(:autoNumber => "AMS"),
-                    :Macros => Dict(
-                        :ket => ["|#1\\rangle", 1],
-                        :bra => ["\\langle#1|", 1],
-                    ),
-                ))),
+                #mathengine = MathJax(Dict(:TeX => Dict(
+                #    :equationNumbers => Dict(:autoNumber => "AMS"),
+                #    :Macros => Dict(
+                #        :ket => ["|#1\\rangle", 1],
+                #        :bra => ["\\langle#1|", 1],
+                #    ),
+                #))),
+                mathengine = MathJax3(Dict(
+                    :loader => Dict("load" => ["[tex]/physics"]),
+                    :tex => Dict("packages" => Dict("[+]" => "physics")),
+                )),
                 highlights = ["erlang", "erlang-repl"],
             )
         )