Convert admonition blockquotes to sections for screen reader users

assets/css/content/admonition.css

@@ -1,36 +1,36 @@
-.content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) {
+.content-inner section.admonition:is(.warning, .error, .info, .neutral, .tip) {
   border-radius: 10px;
   border-left: 0;
 }
 
-.content-inner blockquote.warning {
+.content-inner section.admonition.warning {
   background-color: var(--warningBackground);
 }
 
-.content-inner blockquote.error {
+.content-inner section.admonition.error {
   background-color: var(--errorBackground);
 }
 
-.content-inner blockquote.info {
+.content-inner section.admonition.info {
   background-color: var(--infoBackground);
 }
 
-.content-inner blockquote.neutral {
+.content-inner section.admonition.neutral {
   background-color: var(--neutralBackground);
 }
 
-.content-inner blockquote.tip {
+.content-inner section.admonition.tip {
   background-color: var(--tipBackground);
 }
 
-.content-inner blockquote :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) {
+.content-inner section.admonition :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) {
   color: var(--contrast);
   margin: 0 -1.2rem;
   padding: .7rem 1.2rem .7rem 3.3rem;
   font-weight: 700;
   font-style: normal;
 }
-.content-inner blockquote :is(h3, h4):is(.warning, .error, .info, .neutral, .tip)::before {
+.content-inner section.admonition :is(h3, h4):is(.warning, .error, .info, .neutral, .tip)::before {
   color: var(--contrast);
   position: absolute;
   left: 1rem;
@@ -41,82 +41,82 @@
   -moz-osx-font-smoothing: grayscale;
 }
 
-.content-inner blockquote :is(h3, h4).warning {
+.content-inner section.admonition :is(h3, h4).warning {
   background-color: var(--warningHeadingBackground);
   color: var(--warningHeading);
 }
-.content-inner blockquote :is(h3, h4).warning::before {
+.content-inner section.admonition :is(h3, h4).warning::before {
   content: var(--icon-error-warning);
   color: var(--warningHeading);
 }
 
-.content-inner blockquote :is(h3, h4).error {
+.content-inner section.admonition :is(h3, h4).error {
   background-color: var(--errorHeadingBackground);
   color: var(--errorHeading);
 }
-.content-inner blockquote :is(h3, h4).error::before {
+.content-inner section.admonition :is(h3, h4).error::before {
   content: var(--icon-error-warning);
   color: var(--errorHeading);
 }
 
-.content-inner blockquote :is(h3, h4).info {
+.content-inner section.admonition :is(h3, h4).info {
   background-color: var(--infoHeadingBackground);
   color: var(--infoHeading);
 }
-.content-inner blockquote :is(h3, h4).info::before {
+.content-inner section.admonition :is(h3, h4).info::before {
   content: var(--icon-information);
   color: var(--infoHeading);
 }
 
-.content-inner blockquote :is(h3, h4).neutral {
+.content-inner section.admonition :is(h3, h4).neutral {
   background-color: var(--neutralHeadingBackground);
   color: var(--neutralHeading);
 }
-.content-inner blockquote :is(h3, h4).neutral::before {
+.content-inner section.admonition :is(h3, h4).neutral::before {
   content: var(--icon-double-quotes-l);
   color: var(--neutralHeading);
 }
 
-.content-inner blockquote :is(h3, h4).tip {
+.content-inner section.admonition :is(h3, h4).tip {
   background-color: var(--tipHeadingBackground);
   color: var(--tipHeading);
 }
-.content-inner blockquote :is(h3, h4).tip::before {
+.content-inner section.admonition :is(h3, h4).tip::before {
   content: var(--icon-information);
   color: var(--tipHeading);
 }
 
-.content-inner blockquote :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) code {
+.content-inner section.admonition :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) code {
   margin: 0 0.5ch;
 }
 
-.content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) code {
+.content-inner section.admonition:is(.warning, .error, .info, .neutral, .tip) code {
   background-color: var(--admInlineCodeBackground);
   border: 1px solid var(--admInlineCodeBorder);
   color: var(--admInlineCodeColor);
 }
 
-.content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) pre code {
+.content-inner section.admonition:is(.warning, .error, .info, .neutral, .tip) pre code {
   background-color: var(--admCodeBackground);
   border: 1px solid var(--admCodeBorder);
   color: var(--admCodeColor);
 }
 
-.content-inner blockquote :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) :is(a, a:visited) {
+.content-inner section.admonition :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) :is(a, a:visited) {
   color: inherit;
   text-decoration-color: currentColor;
 }
 
 @media screen and (max-width: 768px) {
-  .content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) {
+  .content-inner section.admonition:is(.warning, .error, .info, .neutral, .tip) {
     margin-left: calc(-1 * var(--content-gutter));
     margin-right: calc(-1 * var(--content-gutter));
     padding-left: var(--content-gutter);
     padding-right: var(--content-gutter);
     border-radius: 0;
   }
 
-  .content-inner blockquote :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) {
+  .content-inner section.admonition :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) {
     margin: 0 calc(-1 * var(--content-gutter));
   }
 }

assets/css/content/epub-admonition.css

@@ -1,4 +1,4 @@
-.content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) {
+.content-inner section.admonition:is(.warning, .error, .info, .neutral, .tip) {
   border-left: solid 4px;
   color: var(--black);
   font-size: 0.9em;
@@ -9,68 +9,68 @@
   page-break-inside: avoid;
 }
 
-.content-inner blockquote.warning {
+.content-inner section.admonition.warning {
   background-color: var(--warningBackground);
   border-left-color: var(--warningHeadingBackground);
 }
 
-.content-inner blockquote.error {
+.content-inner section.admonition.error {
   background-color: var(--errorBackground);
   border-left-color: var(--errorHeadingBackground);
 }
 
-.content-inner blockquote.info {
+.content-inner section.admonition.info {
   background-color: var(--infoBackground);
   border-left-color: var(--infoHeadingBackground);
 }
 
-.content-inner blockquote.neutral {
+.content-inner section.admonition.neutral {
   background-color: var(--neutralBackground);
   border-left-color: var(--neutralHeadingBackground);
 }
 
-.content-inner blockquote.tip {
+.content-inner section.admonition.tip {
   background-color: var(--tipBackground);
   border-left-color: var(--tipHeadingBackground);
 }
 
-.content-inner blockquote :is(h3, h4) {
+.content-inner section.admonition :is(h3, h4) {
   font-weight: bold;
   margin: 0px 10px 5px 0px;
 }
 
-.content-inner blockquote :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) {
+.content-inner section.admonition :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) {
   font-style: normal;
   font-weight: 700;
 }
 
-.content-inner blockquote :is(h3, h4).warning {
+.content-inner section.admonition :is(h3, h4).warning {
   color: var(--warningHeadingBackground);
 }
-.content-inner blockquote :is(h3, h4).error {
+.content-inner section.admonition :is(h3, h4).error {
   color: var(--errorHeadingBackground);
 }
-.content-inner blockquote :is(h3, h4).info {
+.content-inner section.admonition :is(h3, h4).info {
   color: var(--infoHeadingBackground);
 }
-.content-inner blockquote :is(h3, h4).neutral {
+.content-inner section.admonition :is(h3, h4).neutral {
   color: var(--neutralHeadingBackground);
 }
-.content-inner blockquote :is(h3, h4).tip {
+.content-inner section.admonition :is(h3, h4).tip {
   color: var(--tipHeadingBackground);
 }
 
-.content-inner blockquote :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) code {
+.content-inner section.admonition :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) code {
   margin: 0 0.5ch;
 }
 
-.content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) code {
+.content-inner section.admonition:is(.warning, .error, .info, .neutral, .tip) code {
   background-color: var(--admInlineCodeBackground);
   border: 1px solid var(--admInlineCodeBorder);
   color: var(--admInlineCodeColor);
 }
 
-.content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) pre code {
+.content-inner section.admonition:is(.warning, .error, .info, .neutral, .tip) pre code {
   background-color: var(--admCodeBackground);
   border: 1px solid var(--admCodeBorder);
   color: var(--admCodeColor);

assets/css/content/general.css

@@ -97,7 +97,7 @@
   font-weight: normal;
 }
 
-.content-inner blockquote {
+.content-inner blockquote, .content-inner section.admonition {
   border-left: 3px solid var(--blockquoteBorder);
   position: relative;
   margin: 1.5625em 0;
@@ -106,7 +106,7 @@
   background-color: var(--blockquoteBackground);
   border-radius: var(--borderRadius);
 }
-.content-inner blockquote p:last-child {
+.content-inner blockquote p:last-child, .content-inner section.admonition p:last-child  {
   padding-bottom: 1em;
   margin-bottom: 0;
 }

lib/ex_doc/markdown/earmark.ex

@@ -5,6 +5,8 @@ defmodule ExDoc.Markdown.Earmark do
 
   @behaviour ExDoc.Markdown
 
+  @admonition_classes ~w(warning error info tip neutral)
+
   @impl true
   def available? do
     match?({:ok, _}, Application.ensure_all_started(:earmark_parser)) and
@@ -74,6 +76,46 @@ defmodule ExDoc.Markdown.Earmark do
     "$$\n#{content}\n$$"
   end
 
+  # Convert admonition blockquotes to divs for screen reader accessibility
+  defp fixup(
+         {"blockquote", blockquote_attrs,
+          [{tag, h_attrs, _h_content, _h_meta} = h_elem | rest] = ast, blockquote_meta}
+       )
+       when tag in ["h3", "h4"] do
+    h_admonition_classes =
+      h_attrs
+      |> Enum.find("", &match?({"class", _}, &1))
+      |> then(fn
+        "" ->
+          ""
+
+        {"class", classes} ->
+          classes
+          |> String.split(" ")
+          |> Enum.filter(&(&1 in @admonition_classes))
+          |> Enum.join(" ")
+      end)
+
+    if h_admonition_classes != "" do
+      admonition_classes = "admonition #{h_admonition_classes}"
+
+      blockquote_attrs =
+        case Enum.split_with(blockquote_attrs, &match?({"class", _}, &1)) do
+          {[], attrs} ->
+            [{"class", admonition_classes}, {"role", "note"} | attrs]
+
+          {[{"class", classes}], attrs} ->
+            classes = String.trim_trailing(classes) <> " #{admonition_classes}"
+            [{"class", classes}, {"role", "note"} | attrs]
+        end
+
+      fixup({"section", blockquote_attrs, [h_elem | rest], blockquote_meta})
+    else
+      # regular blockquote, copied fixup/1 here to avoid infinite loop
+      {:blockquote, Enum.map(blockquote_attrs, &fixup_attr/1), fixup(ast), blockquote_meta}
+    end
+  end
+
   defp fixup({tag, attrs, ast, meta}) when is_binary(tag) and is_list(attrs) and is_map(meta) do
     {fixup_tag(tag), Enum.map(attrs, &fixup_attr/1), fixup(ast), meta}
   end

test/ex_doc/markdown/earmark_test.exs

@@ -75,6 +75,47 @@ defmodule ExDoc.Markdown.EarmarkTest do
              ]
     end
 
+    test "converts blockquote admonitions to regular divs" do
+      info = """
+      > #### Info {: .info .ignore}
+      > This is info.
+      """
+
+      assert Markdown.to_ast(info, []) == [
+               {:section, [class: "admonition info", role: "note"],
+                [
+                  {:h4, [class: "ignore info"], ["Info"], %{}},
+                  {:p, [], ["This is info."], %{}}
+                ], %{}}
+             ]
+
+      not_admonition = """
+      > ### H3 {: .xyz}
+      > This is NOT an admonition!
+      """
+
+      assert Markdown.to_ast(not_admonition, []) == [
+               {:blockquote, [],
+                [
+                  {:h3, [class: "xyz"], ["H3"], %{}},
+                  {:p, [], ["This is NOT an admonition!"], %{}}
+                ], %{}}
+             ]
+
+      warning_error = """
+      > ### Warning! Error! {: .warning .error}
+      > A warning and an error.
+      """
+
+      assert Markdown.to_ast(warning_error, []) == [
+               {:section, [class: "admonition error warning", role: "note"],
+                [
+                  {:h3, [class: "error warning"], ["Warning! Error!"], %{}},
+                  {:p, [], ["A warning and an error."], %{}}
+                ], %{}}
+             ]
+    end
+
     test "keeps math syntax without interpreting math as markdown" do
       assert Markdown.to_ast("Math $x *y* y$", []) == [
                {:p, [], ["Math ", "$x *y* y$"], %{}}