WIP: experiments with glyphicons in admonitions (notes) (#3231)

* experiments with glyphicons in admonitions (notes)

3 new admonition classes, re-write of test page

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* copyedit on code formatting

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* test Liquid admonitions with includes

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* renamed notes.html, reviewed Liquid relationship to CSS

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

* added description of Liquid variables experiments

Signed-off-by: Victoria Bialas <victoria.bialas@docker.com>

_includes/content/admonitions/notes.html

@@ -0,0 +1,12 @@
+{% if include.type=="note" %}
+{% assign glyphClass="glyphicon glyphicon-ok-sign" %}
+{% assign blockquoteClass="note-vanilla" %}
+{% else if include.type=="warning"%}
+{% assign glyphClass="glyphicon glyphicon-exclamation-sign" %}
+{% assign blockquoteClass="warning-vanilla" %}
+{% else if include.type=="danger"%}
+{% assign glyphClass="glyphicon glyphicon-ban-circle" %}
+{% assign blockquoteClass="danger-vanilla" %}
+{%endif %}
+
+<blockquote class="{{ blockquoteClass }}"><i class="{{ glyphClass }}"></i><b>{{ include.title }}</b><p>{{ include.text | markdownify }}</p></blockquote>

_scss/_notes.scss

@@ -20,6 +20,10 @@ blockquote > p:first-child::before {
   content: 'Note: ';
 }
 
+blockquote.note-vanilla > p:first-child::before {
+  content: '';
+}
+
 blockquote.warning {
   border-left-color: $warning-color;
 }
@@ -32,6 +36,18 @@ blockquote.warning > p:first-child::before {
   content: 'Important: ';
 }
 
+blockquote.warning-vanilla {
+  border-left-color: $warning-color;
+}
+
+blockquote.warning-vanilla > p:first-child {
+  color: $warning-color;
+}
+
+blockquote.warning-vanilla > p:first-child::before {
+  content: '';
+}
+
 blockquote.danger {
   border-left-color: $danger-color;
 }
@@ -44,6 +60,18 @@ blockquote.danger > p:first-child::before {
   content: 'Warning: '
 }
 
+blockquote.danger-vanilla {
+  border-left-color: $danger-color;
+}
+
+blockquote.danger-vanilla > p:first-child {
+  color: $danger-color;
+}
+
+blockquote.danger-vanilla > p:first-child::before {
+  content: ''
+}
+
 /* Maintain backwards compatibility with old
 *  note style
 */

test.md

@@ -363,6 +363,26 @@ Bootstrap JS are loaded.
 
 ## Admonitions (notes)
 
+Current styles for admonitions in
+[`_scss/_notes.scss`](https://github.com/docker/docker.github.io/blob/master/_scss/_notes.scss)
+support to broad categories of admonitions: those with prefixed text (**Note:**,
+**Important:**, **Warning**) and those with prefixed icons.
+
+The new styles (with icons) are defined a way that will not impact notes
+previously formatted with the original styles (prefixed text), so notes in your
+published documents won't be adversely affected.
+
+Both styles are desribed below with examples.
+
+### Examples (original styles, prefix words)
+
+Admonitions with prefixed text use the following class tags, as shown in the examples.
+
+* **Note:** No class tag is needed for standard notes.
+* **Important:** Use the `warning` class.
+* **Warning:** Use the `danger` class.
+
+
 > **Note**: This is a note using the old note style
 
 > **Note**: This is a note using
@@ -375,20 +395,19 @@ Bootstrap JS are loaded.
 > It's not safe out there, take this Moby with you
 >
 > Add the `warning` class to your blockquotes if you want to tell users
-> to be careful about something.
+ to be careful about something.
 {: .warning}
 
 > Ouch, don't do that!
 >
 > Use the `danger` class to let people know this is dangerous or they
-> should pay close attention to this part of the road.
+ should pay close attention to this part of the road.
 >
 > You can also add more paragraphs here if your explanation is
-> super complex.
+ super complex.
 {: .danger}
 
-
-> **This is a crazy note**
+>**This is a crazy note**
 >
 > This note has tons of content in it:
 >
@@ -402,6 +421,99 @@ Bootstrap JS are loaded.
 >
 > And another sentence to top it all off.
 
+### Admonitions with Glyphicons
+
+Let's experiment with some cute [Bootstrap
+Glypicons](http://getbootstrap.com/components/) instead of prefixed text labels. Three new classes have been added to [`_scss/notes.scss`](https://github.com/docker/docker.github.io/blob/master/_scss/_notes.scss):
+
+<span><i class="glyphicon glyphicon-ok-sign"></i> Note text can go here.</span> (Notes use the `note-vanilla` class tag.)
+
+<span><i class="glyphicon glyphicon-exclamation-sign"></i> Text that describes **Important** admonitions can go here.</span> (Important admonitions use the `warning-vanilla`.)
+
+<span><i class="glyphicon glyphicon-ban-circle"></i> Text that describes a **Warning** situation can go here.</span> (Warning admonitions use the `danger-vanilla`.)
+
+The associated pseudo-class definitions for `p:first-child::before` for the new classes all use a null value in `content`, instead of a prefixed word. For example, the standard `warning` class to denote something "Important" uses this:
+
+```none
+blockquote.warning > p:first-child::before {
+  content: 'Important: ';
+}
+```
+
+whereas, `warning-vanilla` uses this:
+
+```none
+blockquote.warning > p:first-child::before {
+  content: '';
+}
+```
+
+So far so good!
+
+### Overhead of using Glyphicons
+
+The problem is there doesn't seem to be a way to call the icons from the CSS.
+You need to add the HTML to call icons directly in the markdown. Examples shown
+below use inline HTML to call the appropriate glypicon for the admonition type,
+with this pattern: `<i class="glyphicon GlypiconName"></i> `.
+
+ |CSS class           | Icon name             |
+ |--------------------|----------------------------------|
+ | `note-vanilla`     | `glyphicon-ok-sign`              |
+ | `warning-vanilla`  | `glyphicon-exclamation-sign`     |
+ | `danger-vanilla`   | `glyphicon glyphicon-ban-circle` |
+
+
+Until we find a way to call the icons directly from the CSS, this approach will
+work, but there is a little more manual overhead involved with adding in the
+HTML prefix to each admonition in the markdown. Check out the raw
+[`test.md`](https://github.com/docker/docker.github.io/blob/master/test.md)
+file.
+
+If we figure out how to call the icons from the CSS, we can replace the null value for `content` in `p:first-child::before` with that call.
+
+### Examples with Glypicons
+
+> <i class="glyphicon glyphicon-ok-sign"></i>  Pssst, wanna know something?
+>
+> You include a small description here telling users to be on the lookout
+>
+> This is an example of a note using the `note-vanilla` tag, which gives you an icon instead of stock prefixed text so that you can write your own title.
+{: .note-vanilla}
+
+> <i class="glyphicon glyphicon-ok-sign"></i> Glyphicon terms of use
+>
+> If we do implement the Glyphicons, we just need to include a link back to [Glyphicons](http://glyphicons.com/) per the use agreement.
+>
+> This is another example of a `note-vanilla` tag.
+{: .note-vanilla}
+
+><i class="glyphicon glyphicon-exclamation-sign"></i> It's not safe out there, take this Moby with you
+>
+> Use the `warning-vanilla` class to get an icon and spice it up yourself with a custom title. Prefix the warning in markdown with `<i class="glyphicon glyphicon-exclamation-sign"></i> ` to get the warning icon.
+{: .warning-vanilla}
+
+><i class="glyphicon glyphicon-exclamation-sign"></i> Leave a space before your custom text
+>
+> With all Glyphicons style notes, make sure the icon isn't smashed up against your custom text. Be sure to leave a space _after_ the `</i>`  and _before_ the closing backtick: `<i class="glyphicon GlypiconName"></i> `
+{: .warning-vanilla}
+
+><i class="glyphicon glyphicon-ban-circle"></i> Ouch, don't touch that hot Docker engine!
+>
+> Use the `danger-vanilla` class to get an icon and spice it up yourself with a custom title. Prefix the warning in markdown with `<i class="glyphicon glyphicon-ban-circle"></i> ` to get the danger icon.
+>
+> You can also add more paragraphs here if your explanation is
+ super complex.
+{: .danger-vanilla}
+
+### Test Liquid admonitions
+
+We are experimenting with a different solution that uses Liquid variables. The following note makes a call to file `content/admonitions/notes.html`, where the Liquid variables are defined to format admonitions. We haven't gotten this totally working yet, and are assessing whether it's a more elegant solution or not.
+
+{% include content/admonitions/notes.html type="warning" title="Do not do this" text="Multiline text is okay!
+
+* See?
+* It's fine!" %}
 
 ## Comments