add support for admonition text blocks (#1400)

Co-authored-by: José Valim <jose.valim@gmail.com>

Author: milmazz

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+.

README.md

@@ -42,11 +42,15 @@ def deps do
 end
 ```
 
-> Note: if you are using Elixir v1.7, v1.8, or v1.9, use `~> 0.22.0`.
+> #### Note {: .info}
+>
+> If you are using Elixir v1.7, v1.8, or v1.9, use `~> 0.22.0`.
 
 After adding ExDoc as a dependency, run `mix deps.get` to install it.
 
-> Note: Some Operating System distributions split Erlang into multiple packages and at least one ExDoc dependency (`earmark_parser`) requires Erlang development environment. If you get a message like "/usr/lib/erlang/lib/parsetools-2.3.1/include/yeccpre.hrl: no such file or directory", it means you lack this environment. For instance, on the Debian operating system and its derivatives, you need to `apt install erlang-dev`.
+> #### Erlang development environment {: .warning}
+>
+> Some Operating System distributions split Erlang into multiple packages and at least one ExDoc dependency (`earmark_parser`) requires Erlang development environment. If you get a message like "/usr/lib/erlang/lib/parsetools-2.3.1/include/yeccpre.hrl: no such file or directory", it means you lack this environment. For instance, on the Debian operating system and its derivatives, you need to `apt install erlang-dev`.
 
 ExDoc will automatically pull in information from your projects, like the application and version. However, you may want to set `:name`, `:source_url` and `:homepage_url` to have a nicer output from ExDoc, such as:
 
@@ -147,6 +151,32 @@ You can also use a custom text, e.g.: `` [custom text](`MyModule.function/1`) ``
 Link to extra pages like this: `` [Up and running](Up and running.md) `` (skipping the directory
 the page is in), the final link will be automatically converted to `up-and-running.html`.
 
+## Admonition blocks
+
+You may want to draw attention to certain statements by taking them out of the
+content's flow and labeling them with a priority. These are called admonitions,
+sometimes are also known as asides or callouts. An admonition block is rendered
+based on the assigned label or class. `ex_doc` supports the following tags:
+`warning`, `error`, `info`, and `neutral` over header levels `h3` and `h4`.
+
+The syntax is as follows:
+
+    > #### Error {: .error}
+    >
+    > This syntax will render an error block
+
+The result for the previous syntax is as follows:
+
+> #### Error {: .error}
+>
+> This syntax will render an error block
+
+For example, if you change the class name to `neutral`, you get:
+
+> #### Error {: .neutral}
+>
+> This syntax will render an error block
+
 ## Extensions
 
 ExDoc renders Markdown content for you, but you can extend it to render complex objects on the page using JavaScript. To inject custom JavaScript into every page, add this to your configuration:

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,98 @@ 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;
+  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;
   }
 
-  *:last-child {
-    padding-bottom: 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.7rem 1.2rem 0.7rem 3.3rem;
+    font-weight: 700;
+    font-style: normal;
+    color: #fff;
+
+    &::before {
+      position: absolute;
+      left: 1rem;
+      font-size: 1.8rem;
+
+      .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;
+      }
+    }
+  }
+
+  p:last-child {
+    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)
+  }
 }

formatters/html/dist/app-a9eda93dd96a056cfa41.js formatters/html/dist/app-073abeeda7b7e6d5d7e9.js

@@ -248,11 +248,52 @@ 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"
+
+    # NOTE: This addition is mainly to preserve the previous `class` attributes
+    # from the headers, in case there is one. Now with the _admonition_ text
+    # block, we inject CSS classes. So far, the supported classes are:
+    # `warning`, `info`, `error`, and `neutral`.
+    #
+    # The Markdown syntax that we support for the admonition text
+    # blocks is something like this:
+    #
+    #     > ### Never open this door! {: .warning}
+    #     >
+    #     > ...
+    #
+    # That should produce the following HTML:
+    #
+    #      <blockquote>
+    #        <h3 class="warning">Never open this door!</h3>
+    #        <p>...</p>
+    #      </blockquote>
+    #
+    # The original implementation discarded the previous CSS classes. Instead,
+    # it was setting `#{section_header_class_name}` as the only CSS class
+    # associated with the given header.
+    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>

formatters/html/dist/app-a9eda93dd96a056cfa41.js.LICENSE.txt formatters/html/dist/app-073abeeda7b7e6d5d7e9.js.LICENSE.txt

@@ -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