From 9f0d7e54b2176328836fab134e4d6a80898d276b Mon Sep 17 00:00:00 2001
From: Cody Clark <codyclark@google.com>
Date: Fri, 28 Jul 2017 16:59:19 -0700
Subject: [PATCH] Adding Callouts to Docs (#4535)

* Create callouts.css

* Linking callouts.css

* Alphabetical order

* Added doc for using callouts

* Fix link

* Deleting info

* Updates per Ahmet

Added more detailed examples and a common issues section

* Update style-guide.md
---
 _includes/head.html                 |   1 +
 css/callouts.css                    |  19 +++++
 docs/home/contribute/style-guide.md | 105 ++++++++++++++++++++++++++++
 3 files changed, 125 insertions(+)
 create mode 100644 css/callouts.css

diff --git a/_includes/head.html b/_includes/head.html
index 87c4a4f175..0410510070 100644
--- a/_includes/head.html
+++ b/_includes/head.html
@@ -7,6 +7,7 @@
     {% if page.case_study_styles %}<link rel="stylesheet" type="text/css" href="/css/case_study_styles.css"><!-- custom case_study_styles on -->{% else %}<link rel="stylesheet" type="text/css" href="/css/styles.css"><!-- default styles.css on -->{% endif %}
     <link rel="stylesheet" type="text/css" href="/css/jquery-ui.min.css">
     <link rel="stylesheet" type="text/css" href="/css/sweetalert.css">
+    <link rel="stylesheet" type="text/css" href="/css/callouts.css">
     {% if page.class == "gridPage" %}<link rel="stylesheet" type="text/css" href="/css/gridpage.css">{% endif %}
     {% if page.css %}<link rel="stylesheet" type="text/css" href="{{ page.css }}"><!-- custom css added -->{% else %}<!-- no custom css detected -->{% endif %}
 
diff --git a/css/callouts.css b/css/callouts.css
new file mode 100644
index 0000000000..f3f34bbaee
--- /dev/null
+++ b/css/callouts.css
@@ -0,0 +1,19 @@
+.caution, .note, .warning {
+    padding: 20px;
+    margin: 20px 0;
+    border: 1px solid #eee;
+    border-left-width: 5px;
+    border-radius: 3px;
+}
+
+.caution {
+    border-left-color: #f0ad4e;
+}
+
+.note {
+    border-left-color: #428bca;
+}
+
+.warning {
+    border-left-color: #d9534f;
+}
diff --git a/docs/home/contribute/style-guide.md b/docs/home/contribute/style-guide.md
index a8277f8198..3945937866 100644
--- a/docs/home/contribute/style-guide.md
+++ b/docs/home/contribute/style-guide.md
@@ -137,6 +137,111 @@ A list of Kubernetes-specific terms and words to be used consistently across the
   <tr><td>TBD</td><td>TBD</td></tr>
 </table>{% endcomment %}
 
+## Callout Formatting
+Callouts help create different rhetorical appeal levels. Our documentation supports three different callouts: **Note:** {: .note}, **Caution:** {: .caution}, and **Warning:** {: .warning}. 
+
+1. Start each callout with the appropriate prefix.
+
+2. Use the following syntax to apply a style:
+
+```console
+**Note:** The prefix you use is the same text you use in the tag. 
+{: .note} <!-- This tag must appear on a new line. -->
+```
+
+The output is:
+
+**Note:** The prefix you choose is the same text for the tag.
+{: .note}
+
+### Note
+
+Use {: .note} to highlight a tip or a piece of information that may be helpful to know. 
+
+For example:
+
+```console
+**Note:** You can _still_ use Markdown inside these callouts. 
+{: .note}
+```
+
+The output is:
+
+**Note:** You can _still_ use Markdown inside these callouts.
+{: .note}
+
+### Caution
+
+Use {: .caution} to call attention to an important piece of information to avoid pitfalls.  
+
+For example:
+
+```console
+**Caution:** The callout style only applies to the line directly above the tag. 
+{: .caution}
+```
+
+The output is:
+
+**Caution:** The callout style only applies to the line directly above the tag. 
+{: .caution}
+
+### Warning
+
+Use {: .warning} to indicate danger or a piece of information that is crucial to follow.
+
+For example:
+
+```console
+**Warning:** Beware. 
+{: .warning}
+```
+
+The output is:
+
+**Warning:** Beware. 
+{: .warning}
+
+## Common Callout Issues
+
+### Style Does Not Apply
+
+Callout tags must be on a new line to apply the style. Github's Preview Changes feature further obfuscates this fact by rendering the tag on the same line, but your code must match the following syntax:
+
+```console
+**Note:** Your text goes here.
+{: .note} <!-- This tag must appear on a new line. -->
+```
+
+### Multiple Lines
+
+Callouts should generally be single sentences and automatically span multiple lines. However, you can use `<br/>` tags if you need to create multiple lines.
+
+For example:
+
+```console
+**Note:"** This is my note. Use `<br/>` to create multiple lines. <br/> <br/> You can still use _Markdown_ to **format** text!
+{: .note}
+```
+
+The output is:
+
+**Note:** This is my note. Use `<br/>` to create multiple lines. <br/> <br/> You can still use _Markdown_ to **format** text!
+{: .note}
+
+Typing multiple lines does **not** work. The callout style only applies to the line directly above the tag. 
+
+```console
+**Note:** This is my note. 
+
+I didn't read the stlye guide.
+{: .note}
+```
+
+**Note:** This is my note. 
+
+I didn't read the stlye guide.
+{: .note}
 
 ## Content best practices