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)
+  }
 }