Skip to content

Commit

Permalink
Pass non-standard admonition categories on in HTML output (#1280)
Browse files Browse the repository at this point in the history
(cherry picked from commit 6e92252)
  • Loading branch information
mortenpi committed Apr 8, 2020
1 parent e71b24d commit f4b4fde
Show file tree
Hide file tree
Showing 4 changed files with 42 additions and 9 deletions.
6 changes: 6 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,9 @@
# Documenter.jl changelog

## 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])
Expand Down Expand Up @@ -529,6 +533,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
Expand Down
34 changes: 27 additions & 7 deletions src/Writers/HTMLWriter.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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...))
)
Expand Down
6 changes: 6 additions & 0 deletions test/examples/src/man/style.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
5 changes: 3 additions & 2 deletions test/examples/tests.jl
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down

0 comments on commit f4b4fde

Please sign in to comment.