diff --git a/assets/html/js/highlight.js b/assets/html/js/highlight.js
deleted file mode 100644
index c8ef6dd1c0c..00000000000
--- a/assets/html/js/highlight.js
+++ /dev/null
@@ -1,7 +0,0 @@
-// libraries: jquery, highlight, highlight-julia, highlight-julia-repl
-// arguments: $, hljs
-
-// Initialize the highlight.js highlighter
-$(document).ready(function() {
- hljs.initHighlighting();
-})
diff --git a/docs/make.jl b/docs/make.jl
index 418bc528543..64b4fc4d34b 100644
--- a/docs/make.jl
+++ b/docs/make.jl
@@ -18,6 +18,7 @@ makedocs(
canonical = "https://juliadocs.github.io/Documenter.jl/stable/",
assets = ["assets/favicon.ico"],
analytics = "UA-136089579-2",
+ highlights = ["yaml"],
),
clean = false,
sitename = "Documenter.jl",
diff --git a/src/Writers/HTMLWriter.jl b/src/Writers/HTMLWriter.jl
index 2c9b5f72ab0..96b3480b165 100644
--- a/src/Writers/HTMLWriter.jl
+++ b/src/Writers/HTMLWriter.jl
@@ -116,6 +116,14 @@ for more information.
Setting it to `false` can be useful when the logo already contains the name of the package.
Defaults to `true`.
+**`highlights`** can be used to add highlighting for additional languages. By default,
+Documenter already highlights all the ["Common" highlight.js](https://highlightjs.org/download/)
+languages and Julia (`julia`, `julia-repl`). Additional languages must be specified by"
+their filenames as they appear on [CDNJS](https://cdnjs.com/libraries/highlight.js) for the
+highlight.js version Documenter is using. E.g. to include highlighting for YAML and LLVM IR,
+you would set `highlights = ["llvm", "yaml"]`. Note that no verification is done whether the
+provided language names are sane.
+
# Default and custom assets
Documenter copies all files under the source directory (e.g. `/docs/src/`) over
@@ -151,6 +159,7 @@ struct HTML <: Documenter.Writer
analytics :: String
collapselevel :: Int
sidebar_sitename :: Bool
+ highlights :: Vector{String}
function HTML(;
prettyurls :: Bool = true,
@@ -161,10 +170,11 @@ struct HTML <: Documenter.Writer
analytics :: String = "",
collapselevel :: Integer = 2,
sidebar_sitename :: Bool = true,
+ highlights :: Vector{String} = String[],
)
collapselevel >= 1 || thrown(ArgumentError("collapselevel must be >= 1"))
new(prettyurls, disable_git, edit_branch, canonical, assets, analytics,
- collapselevel, sidebar_sitename)
+ collapselevel, sidebar_sitename, highlights)
end
end
@@ -180,7 +190,7 @@ const katex_css = "https://cdn.jsdelivr.net/npm/katex@0.10.2/dist/katex.min.css"
"Provides a namespace for JS dependencies."
module JS
- using ....Utilities.JSDependencies: RemoteLibrary
+ using ....Utilities.JSDependencies: RemoteLibrary, Snippet, RequireJS, jsescape
const jquery = RemoteLibrary("jquery", "https://cdnjs.cloudflare.com/ajax/libs/jquery/3.1.1/jquery.min.js")
const jqueryui = RemoteLibrary("jqueryui", "https://cdnjs.cloudflare.com/ajax/libs/jqueryui/1.12.0/jquery-ui.min.js")
const headroom = RemoteLibrary("headroom", "https://cdnjs.cloudflare.com/ajax/libs/headroom/0.9.4/headroom.min.js")
@@ -196,19 +206,36 @@ module JS
"https://cdnjs.cloudflare.com/ajax/libs/KaTeX/0.10.2/contrib/auto-render.min.js",
deps = ["katex"],
)
- const highlight = RemoteLibrary("highlight", "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.15.8/highlight.min.js")
- const highlight_julia = RemoteLibrary(
- "highlight-julia",
- "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.15.8/languages/julia.min.js",
- deps = ["highlight"],
- )
- const highlight_julia_repl = RemoteLibrary(
- "highlight-julia-repl",
- "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/9.15.8/languages/julia-repl.min",
- deps = ["highlight"],
- )
const lunr = RemoteLibrary("lunr", "https://cdnjs.cloudflare.com/ajax/libs/lunr.js/2.3.5/lunr.min.js")
const lodash = RemoteLibrary("lodash", "https://cdnjs.cloudflare.com/ajax/libs/lodash.js/4.17.11/lodash.min.js")
+
+ # highlight.js
+ "Add the highlight.js dependencies and snippet to a [`RequireJS`](@ref) declaration."
+ function highlightjs!(r::RequireJS, languages = String[])
+ hljs_version = "9.15.9"
+ push!(r, RemoteLibrary(
+ "highlight",
+ "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/$(hljs_version)/highlight.min.js"
+ ))
+ prepend!(languages, ["julia", "julia-repl"])
+ for language in languages
+ language = jsescape(language)
+ push!(r, RemoteLibrary(
+ "highlight-$(language)",
+ "https://cdnjs.cloudflare.com/ajax/libs/highlight.js/$(hljs_version)/languages/$(language).min.js",
+ deps = ["highlight"]
+ ))
+ end
+ push!(r, Snippet(
+ vcat(["jquery", "highlight"], ["highlight-$(jsescape(language))" for language in languages]),
+ ["\$", "hljs"],
+ raw"""
+ $(document).ready(function() {
+ hljs.initHighlighting();
+ })
+ """
+ ))
+ end
end
struct SearchRecord
@@ -304,9 +331,9 @@ function render(doc::Documents.Document, settings::HTML=HTML())
else
r = JSDependencies.RequireJS([
JS.jquery, JS.jqueryui, JS.headroom, JS.headroom_jquery,
- JS.highlight, JS.highlight_julia, JS.highlight_julia_repl,
JS.katex, JS.katex_auto_render,
])
+ JS.highlightjs!(r, settings.highlights)
for filename in readdir(joinpath(ASSETS, "js"))
path = joinpath(ASSETS, "js", filename)
endswith(filename, ".js") && isfile(path) || continue
diff --git a/test/examples/make.jl b/test/examples/make.jl
index 3e76c3aeeef..4f7349c70cc 100644
--- a/test/examples/make.jl
+++ b/test/examples/make.jl
@@ -201,6 +201,7 @@ examples_html_deploy_doc = @quietly withassets("images/logo.png", "images/logo.j
],
prettyurls = true,
canonical = "https://example.com/stable",
+ highlights = ["erlang", "erlang-repl"],
)
)
end
diff --git a/test/examples/tests.jl b/test/examples/tests.jl
index f5c62d48091..3ef5b33f3a3 100644
--- a/test/examples/tests.jl
+++ b/test/examples/tests.jl
@@ -91,6 +91,12 @@ end
@test isfile(joinpath(build_dir, "omitted.html"))
@test isfile(joinpath(build_dir, "hidden.html"))
@test isfile(joinpath(build_dir, "lib", "autodocs.html"))
+
+ # Assets
+ @test joinpath(build_dir, "assets", "documenter.js") |> isfile
+ documenterjs = String(read(joinpath(build_dir, "assets", "documenter.js")))
+ @test occursin("languages/julia.min", documenterjs)
+ @test occursin("languages/julia-repl.min", documenterjs)
end
end
@@ -106,6 +112,16 @@ end
@test joinpath(build_dir, "omitted", "index.html") |> isfile
@test joinpath(build_dir, "hidden", "index.html") |> isfile
@test joinpath(build_dir, "lib", "autodocs", "index.html") |> isfile
+
+ # Assets
+ @test joinpath(build_dir, "assets", "documenter.js") |> isfile
+
+ # This build includes erlang and erlang-repl highlighting
+ documenterjs = String(read(joinpath(build_dir, "assets", "documenter.js")))
+ @test occursin("languages/julia.min", documenterjs)
+ @test occursin("languages/julia-repl.min", documenterjs)
+ @test occursin("languages/erlang-repl.min", documenterjs)
+ @test occursin("languages/erlang.min", documenterjs)
end
end
end