From 4b5ce015de88fac26b92ed2a9419df3037eba74d Mon Sep 17 00:00:00 2001
From: Tammy Fox <tammy@docker.com>
Date: Fri, 3 Aug 2018 15:45:39 -0400
Subject: [PATCH] clarify admonition code and how they render

---
 test.md | 66 ++++++++++++++++++++++++---------------------------------
 1 file changed, 28 insertions(+), 38 deletions(-)

diff --git a/test.md b/test.md
index c798793bd5..e3c12a0d8b 100644
--- a/test.md
+++ b/test.md
@@ -586,66 +586,56 @@ Current styles for admonitions in
 [`_scss/_notes.scss`](https://github.com/docker/docker.github.io/blob/master/_scss/_notes.scss)
 support these broad categories of admonitions:
 
-- Notes in the old style (no Liquid tag required)
-- Notes with a prefixed icon (no Liquid tag required)
-- Important and Warning admonitions, which take `{: .important}` and `{: .warning}` tags, respectively
+- Notes (no Liquid tag required) (deprecated)
+- Important, which use the `{: .important}` tag
+- Warning , which use the `{: .warning}` tag
 
 The new styles include prepended icons, color sidebars, and bold color titles
 for multi-paragraph notes, but no auto-prepended text. These are defined in a
 way that does not impact admonitions formatted with the original styles, so
 notes in your published documents are not adversely affected.
 
-Examples of both styles are shown below.
+Examples are shown in the following sections.
 
-### Examples (original styles, prefix words)
-
-Admonitions with prefixed icons use the following class tags, as shown in the examples.
-
-* **Note:** No class tag is needed for standard notes.
-* **Important:** Use the `important` class.
-* **Warning:** Use the `warning` class.
+### Note (Deprecated)
 
+A standard note is formatted like this:
 
+```
 > **Note**: This is a note using the old note style
+```
 
+They will still render with a colored sidebar to the left, but they should not longer be used. Use important or warning instead.
+
+### Important
+
+Add the `important` class to your blockquotes if you want to tell users to be careful about something:
+
+```
 > Pssst, wanna know something?
 >
 > You include a small description here telling users to be on the lookout
-
-> It's not safe out there, take this Moby with you
->
-> Add the `important` class to your blockquotes if you want to tell users
- to be careful about something.
 {: .important}
+```
+
+It will render like this:
+
+![important admonition example](/images/important-admonition-example.png)
+
+### Warning
+
+Use the `warning` class to let people know this is dangerous or they should pay close attention to this part of the road before moving on:
 
 > Ouch, don't do that!
 >
-> Use the `warning` class to let people know this is dangerous or they
- should pay close attention to this part of the road.
+> Sticking your finger in an electrical outlet can result in an electric shock.
 >
-> You can also add more paragraphs here if your explanation is
- super complex.
+> You can also add more paragraphs here if your explanation is super complex.
 {: .warning}
 
->**This is a crazy note**
->
-> This note has tons of content in it:
->
-> - List item 1
-> - List item 2
->
-> |Table column 1  | Table column 2 |
-> |----------------|----------------|
-> | Row 1 column 1 | Row 2 column 2 |
-> | Row 2 column 1 | Row 2 column 2 |
->
-> And another sentence to top it all off.
+It will render like this:
 
-> **Important**: Single paragraph important note with the prefix word "important" manually typed in as bold at the beginning.
-{: .important}
-
-> **Warning**: Single paragraph warning with the prefix word "warning" manually typed in as bold at the beginning.
-{: .warning}
+![warning admonition example](/images/warning-admonition-example.png)
 
 ## Code blocks