diff --git a/_includes/content/admonitions/notes.html b/_includes/content/admonitions/notes.html new file mode 100644 index 0000000000..bfd18db841 --- /dev/null +++ b/_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 %} + +
{{ include.title }}

{{ include.text | markdownify }}

diff --git a/_scss/_notes.scss b/_scss/_notes.scss index 4b8cb3bcdf..2a2dce6cbc 100644 --- a/_scss/_notes.scss +++ b/_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 */ diff --git a/test.md b/test.md index 4f44a39e85..92e614c2ac 100644 --- a/test.md +++ b/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): + + Note text can go here. (Notes use the `note-vanilla` class tag.) + + Text that describes **Important** admonitions can go here. (Important admonitions use the `warning-vanilla`.) + + Text that describes a **Warning** situation can go here. (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: ` `. + + |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 + +> 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} + +> 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} + +> 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 ` ` to get the warning icon. +{: .warning-vanilla} + +> 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 `` and _before_ the closing backtick: ` ` +{: .warning-vanilla} + +> 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 ` ` 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