Pass non-standard admonition categories on in HTML output (#1280)

JuliaDocs · Apr 8, 2020 · 6e92252 · 6e92252
1 parent f73af38
commit 6e92252
Show file tree

Hide file tree

Showing 4 changed files with 42 additions and 9 deletions.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,10 @@
 
 * ![Bugfix][badge-bugfix] `Deps.pip` is again a closure and gets executed during the `deploydocs` call, not before it. ([#1240][github-1240])
 
+## Version `v0.24.8`
+
+* ![Enhancement][badge-enhancement] Non-standard admonition categories are (again) applied to the admonition `<div>` elements in HTML output (as `is-category-$category`). ([#1279][github-1279], [#1280][github-1280])
+
 ## Version `v0.24.7`
 
 * ![Bugfix][badge-bugfix] Remove `only`, a new export from `Base` on Julia 1.4, from the JS search filter. ([#1264][github-1264])
@@ -534,6 +538,8 @@
 [github-1258]: https://github.com/JuliaDocs/Documenter.jl/pull/1258
 [github-1264]: https://github.com/JuliaDocs/Documenter.jl/pull/1264
 [github-1269]: https://github.com/JuliaDocs/Documenter.jl/pull/1269
+[github-1279]: https://github.com/JuliaDocs/Documenter.jl/issues/1279
+[github-1280]: https://github.com/JuliaDocs/Documenter.jl/pull/1280
 
 [documenterlatex]: https://github.com/JuliaDocs/DocumenterLaTeX.jl
 [documentermarkdown]: https://github.com/JuliaDocs/DocumenterMarkdown.jl

diff --git a/src/Writers/HTMLWriter.jl b/src/Writers/HTMLWriter.jl
@@ -1595,13 +1595,33 @@ end
 function mdconvert(a::Markdown.Admonition, parent; kwargs...)
     @tags header div
     colorclass =
-        (a.category == "danger")  ? "is-danger"  :
-        (a.category == "warning") ? "is-warning" :
-        (a.category == "note")    ? "is-info"    :
-        (a.category == "info")    ? "is-info"    :
-        (a.category == "tip")     ? "is-success" :
-        (a.category == "compat")  ? "is-compat"  : ""
-    div[".admonition.$(colorclass)"](
+        (a.category == "danger")  ? ".is-danger"  :
+        (a.category == "warning") ? ".is-warning" :
+        (a.category == "note")    ? ".is-info"    :
+        (a.category == "info")    ? ".is-info"    :
+        (a.category == "tip")     ? ".is-success" :
+        (a.category == "compat")  ? ".is-compat"  : begin
+            # If the admonition category is not one of the standard ones, we tag the
+            # admonition div element with a `is-category-$(category)` class. However, we
+            # first carefully sanitize the category name. Strictly speaking, this is not
+            # necessary when were using the Markdown parser in the Julia standard library,
+            # since it restricts the category to [a-z]+. But it is possible for the users to
+            # construct their own Admonition objects with arbitrary category strings and
+            # pass them onto Documenter.
+            #
+            # (1) remove all characters except A-Z, a-z, 0-9 and -
+            cat_sanitized = replace(a.category, r"[^A-Za-z0-9-]" => "")
+            # (2) remove any dashes from the beginning and end of the string
+            cat_sanitized = replace(cat_sanitized, r"^[-]+" => "")
+            cat_sanitized = replace(cat_sanitized, r"[-]+$" => "")
+            # (3) reduce any duplicate dashes in the middle to single dashes
+            cat_sanitized = replace(cat_sanitized, r"[-]+" => "-")
+            cat_sanitized = lowercase(cat_sanitized)
+            # (4) if nothing is left (or the category was empty to begin with), we don't
+            # apply a class
+            isempty(cat_sanitized) ? "" : ".is-category-$(cat_sanitized)"
+        end
+    div[".admonition$(colorclass)"](
         header[".admonition-header"](a.title),
         div[".admonition-body"](mdconvert(a.content, a; kwargs...))
     )

diff --git a/test/examples/src/man/style.md b/test/examples/src/man/style.md
@@ -20,6 +20,12 @@ In an admonition it looks like this:
     * Nulla quis venenatis justo.
     * In non _sodales_ eros.
 
+Also, custom admonition classes can be used:
+
+!!! myadmonition "My Admonition Class"
+
+    In the HTML output, this admonition has `is-category-myadmonition` applied to it.
+
 But otherwise
 
 * Lorem ipsum dolor sit amet, consectetur adipiscing elit.

diff --git a/test/examples/tests.jl b/test/examples/tests.jl
@@ -28,10 +28,11 @@ 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
+            @test joinpath(build_dir, "man", "style", "index.html") |> isfile
 
             # Test existence of some HTML elements
-            indexhtml = String(read(joinpath(build_dir, "index.html")))
-            #@test occursin("", indexhtml)
+            man_style_html = String(read(joinpath(build_dir, "man", "style", "index.html")))
+            @test occursin("is-category-myadmonition", man_style_html)
 
             # Assets
             @test joinpath(build_dir, "assets", "documenter.js") |> isfile