Creation of liquid-based notes/documentation of approach

_includes/note.html

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

test.md

@@ -363,157 +363,61 @@ 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.
+To create an admonition, include `note.html` and send it the following three
+parameters:
 
-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.
+| Parameter | Description |
+| --------- | ----------- |
+| `type` | Can be `note`, `important`, or `warning` for blue, yellow, or red notes, respectively. |
+| `title` | The title of the note; this will be shown in bold, next to a glyphicon. |
+| `text` | The text of the note, in markdown. While it must be within quotation marks, it can still be multi-line -- just be sure to backslash-escape any quote characters. |
 
-Both styles are desribed below with examples.
+### Example of type `note`
 
-### Examples (original styles, prefix words)
+{% include note.html type="note" title="Note example right here" text="Multiline text is okay!
 
-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
-> the old style and has multiple lines, but a single paragraph
-
-> 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 `warning` class to your blockquotes if you want to tell users
- 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.
->
-> You can also add more paragraphs here if your explanation is
- super complex.
-{: .danger}
-
->**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.
-
-### 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`.)
+* See?
+* It's fine!
 
-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:
+**Here's how I was generated**:
 
-```none
-blockquote.warning > p:first-child::before {
-  content: 'Important: ';
-}
 ```
+{% include note.html type=\"note\" title=\"Note example right here\" text=\"Multiline text is okay!
 
-whereas, `warning-vanilla` uses this:
-
-```none
-blockquote.warning > p:first-child::before {
-  content: '';
-}
+* See?
+* It's fine!\"
 ```
 
-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> `.
+Two caveats:
 
- |CSS class           | Icon name             |
- |--------------------|----------------------------------|
- | `note-vanilla`     | `glyphicon-ok-sign`              |
- | `warning-vanilla`  | `glyphicon-exclamation-sign`     |
- | `danger-vanilla`   | `glyphicon glyphicon-ban-circle` |
+1. Backslash-escaping quotes is necessary.
+2. The literal printing of liquid syntax within a note does not work -- it will always get interpreted. This is why the closing marker of the `include` is not shown.
+" %}
 
+### Example of type `important`
 
-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.
+{% include note.html type="important" title="Important example right here" text="Multiline text is okay!
 
-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}
+* See?
+* It's fine!
 
-><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 was generated the same way as above, but `type` was set to `important`." %}
 
-><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}
+### Example of type `warning`
 
-### Test Liquid admonitions
+{% include note.html type="warning" title="Warning example right here" text="Multiline text is okay!
 
-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.
+* See?
+* It's fine!
 
-{% include content/admonitions/notes.html type="warning" title="Do not do this" text="Multiline text is okay!
+#### Inline table
 
-* See?
-* It's fine!" %}
+| Parameter | Description |
+| --------- | ----------- |
+| `type` | Can be `note`, `important`, or `warning` for blue, yellow, or red notes, respectively. |
+| `title` | The title of the note; this will be shown in bold. |
+| `text` | The text of the note, in markdown. While it must be within quotation marks, it can still be multi-line. |
+" %}
 
 ## Comments