add support for admonition text blocks

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [Unreleased]
+
+  * Enhancements
+    * Add support for admonition text blocks
+    * Improve accessibility for light and dark themes
+
+  * Bug fixes
+    * Ensure that `mix docs --open` works on Windows
+
 ## v0.28.0 (2022-01-24)
 
 ExDoc v0.28.0 requires Elixir v1.11+.

assets/js/content.js

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

assets/less/content/general.less

@@ -101,18 +101,99 @@ h1 .note {
 
 blockquote {
   font-style: italic;
-  margin: .5em 0;
-  padding: .25em 1.5em;
   border-left: 3px solid @gray;
-  display: inline-block;
+  position: relative;
+  margin: 1.5625em 0;
+  padding: 0 1.2rem;
+  font-size: 1.28rem;
+  overflow: auto;
+  background-color: #f6f6f6;
+  border-radius: 3px;
 
-  *:first-child {
-    padding-top: 0;
-    margin-top: 0;
+  &.warning,
+  &.error,
+  &.info,
+  &.neutral {
+    color: #000;
+    border-radius: 10px;
+    border-left: 0;
+  }
+
+  &.warning {
+    background-color: #fff7ed;
+  }
+
+  &.error {
+    background-color: #fdeeec;
+  }
+
+  &.info {
+    background-color: #e9f5fe;
+  }
+
+  &.neutral {
+    background-color: #e2e8ef;
+  }
+
+  h3.warning,
+  h3.error,
+  h3.info,
+  h3.neutral,
+  h4.warning,
+  h4.error,
+  h4.info,
+  h4.neutral {
+    margin: 0 -1.2rem;
+    padding: 0.8rem 1.2rem 0.8rem 4rem;
+    font-weight: 700;
+    font-style: normal;
+    color: #fff;
+
+    &::before {
+      position: absolute;
+      left: 1.2rem;
+      font-size: 2rem;
+
+      .remix-icon
+    }
+
+    &.warning {
+      background-color: #f3ac55;
+      color: #000;
+
+      &::before {
+        color: #000;
+        content: @icon-error-warning;
+      }
+    }
+
+    &.error {
+      background-color: #eb5949;
+
+      &::before {
+        content: @icon-error-warning;
+      }
+    }
+
+    &.info {
+      background-color: #4496f7;
+
+      &::before {
+        content: @icon-information;
+      }
+    }
+
+    &.neutral {
+      background-color: #101828;
+
+      &::before {
+        content: @icon-double-quotes-l;
+      }
+    }
   }
 
   *:last-child {
-    padding-bottom: 0;
+    padding-bottom: 1em;
     margin-bottom: 0;
   }
 }

assets/less/icons.less

@@ -21,16 +21,30 @@
 @icon-arrow-right-s: "\ea6e";
 @icon-add: "\ea13";
 @icon-subtract: "\f1af";
+@icon-error-warning: "\eca1";
+@icon-information: "\ee59";
+@icon-alert: "\ea21";
+@icon-double-quotes-l: "\ec51";
+@icon-link-m: "\eeaf";
+@icon-close-line: "\eb99";
+@icon-code-s-slash-line: "\ebad";
+@icon-menu-line: "\ef3e";
+@icon-search-2-line: "\f0cd";
+@icon-settings-3-line: "\f0e6";
 
 .ri-lg { font-size: 1.3333em; line-height: 0.75em; vertical-align: -.0667em; }
-.ri-settings-3-line:before { content: "\f0e6"; }
-.ri-add-line:before { content: "\ea13"; }
-.ri-subtract-line:before { content: "\f1af"; }
-.ri-arrow-up-s-line:before { content: "\ea78"; }
-.ri-arrow-down-s-line:before { content: "\ea4e"; }
-.ri-arrow-right-s-line:before { content: "\ea6e"; }
-.ri-search-2-line:before { content: "\f0cd"; }
-.ri-menu-line:before { content: "\ef3e"; }
-.ri-close-line:before { content: "\eb99"; }
-.ri-link-m:before { content: "\eeaf"; }
-.ri-code-s-slash-line:before { content: "\ebad"; }
+.ri-settings-3-line:before { content: @icon-settings-3-line; }
+.ri-add-line:before { content: @icon-add; }
+.ri-subtract-line:before { content: @icon-subtract; }
+.ri-arrow-up-s-line:before { content: @icon-arrow-up-s; }
+.ri-arrow-down-s-line:before { content: @icon-arrow-down-s; }
+.ri-arrow-right-s-line:before { content: @icon-arrow-right-s; }
+.ri-search-2-line:before { content: @icon-search-2-line; }
+.ri-menu-line:before { content: @icon-menu-line; }
+.ri-close-line:before { content: @icon-close-line; }
+.ri-link-m:before { content: @icon-link-m; }
+.ri-code-s-slash-line:before { content: @icon-code-s-slash-line; }
+.ri-error-warning-line:before { content: @icon-error-warning; }
+.ri-information-line:before { content: @icon-information; }
+.ri-alert-line:before { content: @icon-alert; }
+.ri-double-quotes-l:before { content: @icon-double-quotes-l; }

assets/less/night/night.less

@@ -16,4 +16,9 @@ body.night-mode {
       color: @main;
     }
   }
+
+  blockquote {
+    border-left: 3px solid rgb(68, 68, 76);
+    background-color: rgb(44, 44, 49)
+  }
 }

lib/ex_doc/formatter/html/templates.ex

@@ -248,11 +248,30 @@ defmodule ExDoc.Formatter.HTML.Templates do
     |> elem(0)
   end
 
+  @class_regex ~r/<h[23].*?(\sclass="(?<class>[^"]+)")?.*?>/
+  @class_separator " "
   defp link_heading(match, _tag, _title, "", _prefix), do: match
 
-  defp link_heading(_match, tag, title, id, prefix) do
+  defp link_heading(match, tag, title, id, prefix) do
+    section_header_class_name = "section-heading"
+
+    class_attribute =
+      case Regex.named_captures(@class_regex, match) do
+        %{"class" => ""} ->
+          section_header_class_name
+
+        %{"class" => previous_classes} ->
+          # Let's make sure that the `section_header_class_name` is not already
+          # included in the previous classes for the header
+          previous_classes
+          |> String.split(@class_separator)
+          |> Enum.reject(&(&1 == section_header_class_name))
+          |> Enum.join(@class_separator)
+          |> Kernel.<>(" #{section_header_class_name}")
+      end
+
     """
-    <#{tag} id="#{prefix}#{id}" class="section-heading">
+    <#{tag} id="#{prefix}#{id}" class="#{class_attribute}">
       <a href="##{prefix}#{id}" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i>
       <p class="sr-only">#{id}</p>
       </a>

test/ex_doc/formatter/html/templates_test.exs

@@ -144,6 +144,22 @@ defmodule ExDoc.Formatter.HTML.TemplatesTest do
              </h3>
              """
     end
+
+    test "generates headers for admonition support" do
+      admonition_block = """
+      <blockquote><h3 class="warning">Foo</h3></blockquote>
+      """
+
+      assert Templates.link_headings(admonition_block) == """
+             <blockquote><h3 id="foo" class="warning section-heading">
+               <a href="#foo" class="hover-link"><i class="ri-link-m" aria-hidden="true"></i>
+               <p class="sr-only">foo</p>
+               </a>
+               Foo
+             </h3>
+             </blockquote>
+             """
+    end
   end
 
   describe "synopsis" do