From f55959e58e77429be6af3deb12f4cbae5c80db8f Mon Sep 17 00:00:00 2001 From: Morten Piibeleht Date: Sun, 18 Aug 2019 22:03:19 +1200 Subject: [PATCH] Add an option to include additional highlight.js languages --- assets/html/js/highlight.js | 7 ----- docs/make.jl | 1 + src/Writers/HTMLWriter.jl | 55 +++++++++++++++++++++++++++---------- test/examples/make.jl | 1 + test/examples/tests.jl | 16 +++++++++++ 5 files changed, 59 insertions(+), 21 deletions(-) delete mode 100644 assets/html/js/highlight.js 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