Convert admonition blockquotes to sections for screen reader users (#1938)

Some screen readers will announce that an element is a blockquote.
It could be potentially surprising to hear something announced as a
blockquote despite the inner contents not being a quote.

Author: voughtdq

assets/css/content/admonition.css

@@ -1,36 +1,36 @@
-.content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) {
+.content-inner section.admonition {
   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 > .admonition-title {
   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 > .admonition-title::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 > .admonition-title.warning {
   background-color: var(--warningHeadingBackground);
   color: var(--warningHeading);
 }
-.content-inner blockquote :is(h3, h4).warning::before {
+.content-inner section.admonition > .admonition-title.warning::before {
   content: var(--icon-error-warning);
   color: var(--warningHeading);
 }
 
-.content-inner blockquote :is(h3, h4).error {
+.content-inner section.admonition > .admonition-title.error {
   background-color: var(--errorHeadingBackground);
   color: var(--errorHeading);
 }
-.content-inner blockquote :is(h3, h4).error::before {
+.content-inner section.admonition > .admonition-title.error::before {
   content: var(--icon-error-warning);
   color: var(--errorHeading);
 }
 
-.content-inner blockquote :is(h3, h4).info {
+.content-inner section.admonition > .admonition-title.info {
   background-color: var(--infoHeadingBackground);
   color: var(--infoHeading);
 }
-.content-inner blockquote :is(h3, h4).info::before {
+.content-inner section.admonition > .admonition-title.info::before {
   content: var(--icon-information);
   color: var(--infoHeading);
 }
 
-.content-inner blockquote :is(h3, h4).neutral {
+.content-inner section.admonition > .admonition-title.neutral {
   background-color: var(--neutralHeadingBackground);
   color: var(--neutralHeading);
 }
-.content-inner blockquote :is(h3, h4).neutral::before {
+.content-inner section.admonition > .admonition-title.neutral::before {
   content: var(--icon-double-quotes-l);
   color: var(--neutralHeading);
 }
 
-.content-inner blockquote :is(h3, h4).tip {
+.content-inner section.admonition > .admonition-title.tip {
   background-color: var(--tipHeadingBackground);
   color: var(--tipHeading);
 }
-.content-inner blockquote :is(h3, h4).tip::before {
+.content-inner section.admonition > .admonition-title.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 > .admonition-title code {
   margin: 0 0.5ch;
 }
 
-.content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) code {
+.content-inner section.admonition 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  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 > .admonition-title :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 {
     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 > .admonition-title {
     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 {
   border-left: solid 4px;
   color: var(--black);
   font-size: 0.9em;
@@ -9,68 +9,65 @@
   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 > .admonition-title {
   font-weight: bold;
   margin: 0px 10px 5px 0px;
-}
-
-.content-inner blockquote :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 > .admonition-title.warning {
   color: var(--warningHeadingBackground);
 }
-.content-inner blockquote :is(h3, h4).error {
+.content-inner section.admonition > .admonition-title.error {
   color: var(--errorHeadingBackground);
 }
-.content-inner blockquote :is(h3, h4).info {
+.content-inner section.admonition > .admonition-title.info {
   color: var(--infoHeadingBackground);
 }
-.content-inner blockquote :is(h3, h4).neutral {
+.content-inner section.admonition > .admonition-title.neutral {
   color: var(--neutralHeadingBackground);
 }
-.content-inner blockquote :is(h3, h4).tip {
+.content-inner section.admonition > .admonition-title.tip {
   color: var(--tipHeadingBackground);
 }
 
-.content-inner blockquote :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) code {
+.content-inner section.admonition > .admonition-title code {
   margin: 0 0.5ch;
 }
 
-.content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) code {
+.content-inner section.admonition 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 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;
 }
@@ -178,7 +178,7 @@
   }
 }
 
-.content-inner blockquote .section-heading i {
+.content-inner :is(blockquote, section.admonition) .section-heading i {
   display: none;
 }
 

assets/css/print.css

@@ -52,11 +52,11 @@
     display: none;
   }
 
-  .content-inner blockquote:is(.warning, .error, .info, .neutral, .tip) {
+  .content-inner section.admonition {
     border: 2px solid var(--gray400);
   }
 
-  .content-inner blockquote :is(h3, h4):is(.warning, .error, .info, .neutral, .tip) {
+  .content-inner section.admonition > .admonition-title {
     color: var(--textHeaders);
     border-bottom: 2px solid var(--gray400);
   }

assets/css/tabset.css

@@ -58,7 +58,8 @@
   }
 
   .tabset-panel pre,
-  .tabset-panel blockquote {
+  .tabset-panel blockquote,
+  .tabset-panel section.admonition {
     margin-left: calc(-1 * var(--tabsetPadding)) !important;
     margin-right: calc(-1 * var(--tabsetPadding)) !important;
   }

assets/js/content.js

@@ -16,7 +16,6 @@ export function initialize (isPreview) {
 
   setLivebookBadgeUrl()
   fixLinks()
-  fixBlockquotes()
 }
 
 /**
@@ -30,20 +29,6 @@ function fixLinks () {
   })
 }
 
-/**
- * Add CSS classes to `blockquote` elements when those are used to
- * support admonition text blocks
- */
-export function fixBlockquotes () {
-  const classes = ['warning', 'info', 'error', 'neutral', 'tip']
-
-  classes.forEach(element => {
-    qsAll(`blockquote h3.${element}, blockquote h4.${element}`).forEach(header => {
-      header.closest('blockquote').classList.add(element)
-    })
-  })
-}
-
 /**
  * Focuses the content element.
  *

assets/js/entry/epub.js

@@ -1,8 +1,6 @@
 import { onDocumentReady } from '../helpers'
-import { fixBlockquotes } from '../content'
 import { initialize as initMakeup } from '../makeup'
 
 onDocumentReady(() => {
   initMakeup()
-  fixBlockquotes()
 })

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,47 @@ defmodule ExDoc.Markdown.Earmark do
     "$$\n#{content}\n$$"
   end
 
+  # Convert admonition blockquotes to sections for screen reader accessibility
+  defp fixup(
+         {"blockquote", blockquote_attrs, [{tag, h_attrs, h_content, h_meta} | rest] = ast,
+          blockquote_meta}
+       )
+       when tag in ["h3", "h4"] do
+    h_admonition =
+      with {{"class", classes}, attrs} <- List.keytake(h_attrs, "class", 0),
+           class_list <- String.split(classes, " "),
+           adm_classes = [_ | _] <- Enum.filter(class_list, &(&1 in @admonition_classes)) do
+        {"admonition " <> Enum.join(adm_classes, " "),
+         [{"class", "admonition-title #{classes}"} | attrs]}
+      else
+        _ -> nil
+      end
+
+    section_attrs_fn = fn admonition_classes ->
+      {classes, attrs} =
+        case List.keytake(blockquote_attrs, "class", 0) do
+          nil ->
+            {admonition_classes, blockquote_attrs}
+
+          {{"class", classes}, attrs} ->
+            {"#{admonition_classes} #{classes}", attrs}
+        end
+
+      [{"role", "note"}, {"class", classes} | attrs]
+    end
+
+    if h_admonition do
+      {admonition_classes, h_attrs} = h_admonition
+      section_attrs = section_attrs_fn.(admonition_classes)
+      h_elem = {tag, h_attrs, h_content, h_meta}
+
+      fixup({"section", section_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