Add support for notes and warnings.

There is currently a bug that will cause them to be rendered incorrectly
if they have only one paragraph, but that doesn't matter for the usage
in this PR.

Signed-off-by: Daira Emma Hopwood <daira@jacaranda.org>

css/style.css

@@ -18,6 +18,29 @@
   #index-of-zips table tr:hover {
     background-color: #eff1f2;
   }
+  aside.note {
+    background-color: #a0a0ff;
+    color: #111519;
+  }
+  aside.note::before {
+    background-color: #5858ff;
+    color: #000000;
+  }
+  aside.warning {
+    background-color: #ffb090;
+    color: #111519;
+    font-weight: 500;
+  }
+  aside.warning::before {
+    background-color: #ff7050;
+    font-weight: 600;
+  }
+  aside > p > a, a:visited {
+    color: #0077a1;
+  }
+  aside > p > a:hover {
+    color: #00455c;
+  }
 }
 
 @media (prefers-color-scheme: dark) {
@@ -46,6 +69,57 @@
   #index-of-zips table tr:hover {
     background-color: #303030;
   }
+  aside.note {
+    background-color: #6060e0;
+    color: #ffffff;
+  }
+  aside.note::before {
+    background-color: #3030e0;
+  }
+  aside.warning {
+    background-color: #e08060;
+    color: #ffffff;
+    font-weight: 700;
+  }
+  aside.warning::before {
+    background-color: #e05030;
+    font-weight: 800;
+  }
+  aside > p > a, a:visited {
+    color: #50e7f4;
+  }
+  aside > p > a:hover {
+    color: #90ffff;
+  }
+}
+
+aside {
+  display: flex;
+  flex-direction: column;
+  gap: 1em;
+  padding-top: 0.15rem;
+  padding-left: 0.15rem;
+  padding-right: 0.15rem;
+  padding-bottom: 0;
+  margin-bottom: 1.5rem;
+}
+aside::before {
+  font-size: 130%;
+  padding-top: 0.2rem;
+  padding-left: 1rem;
+  padding-right: 0.2rem;
+  padding-bottom: 0.3rem;
+  margin-bottom: 1.2rem;
+}
+aside.note::before {
+  content: "Note";
+}
+aside.warning::before {
+  content: "Warning";
+}
+aside > p {
+  padding-left: 1rem;
+  padding-right: 1rem;
 }
 
 @font-face {

zip-guide.html

@@ -84,6 +84,16 @@ Pull-Request: &lt;<a href="https://github.com/zcash/zips/pull/253">https://githu
                 , so you will need to double-check that the rendering is as intended.</p>
                 <p>In general the conventions in the Zcash protocol specification SHOULD be followed. If you find this difficult, don't worry too much about it in initial drafts; the ZIP editors will catch any inconsistencies in review.</p>
             </section>
+            <section id="notes-and-warnings"><h3><span class="section-heading">Notes and warnings</span><span class="section-anchor"> <a rel="bookmark" href="#notes-and-warnings"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
+                <aside class="note">
+                    <p>"<code>.. note::</code>" in reStructuredText, or "<code>:::info</code>" (terminated by "<code>:::</code>") in Markdown, can be used for an aside from the main text.</p>
+                    <p>The rendering of notes is colourful and may be distracting, so they should only be used for important points.</p>
+                </aside>
+                <aside class="warning">
+                    <p>"<code>.. warning::</code>" in reStructuredText, or "<code>:::warning</code>" (terminated by "<code>:::</code>") in Markdown, can be used for warnings.</p>
+                    <p>Warnings should be used very sparingly — for example to signal that a entire specification, or part of it, may be inapplicable or could cause significant interoperability or security problems. In most cases, a "MUST" or "SHOULD" conformance requirement is more appropriate.</p>
+                </aside>
+            </section>
             <section id="valid-restructuredtext"><h3><span class="section-heading">Valid reStructuredText</span><span class="section-anchor"> <a rel="bookmark" href="#valid-restructuredtext"><img width="24" height="24" class="section-anchor" src="assets/images/section-anchor.png" alt=""></a></span></h3>
                 <p>This is optional before publishing a PR, but to check whether a document is valid reStructuredText, first install <code>rst2html5</code>. E.g. on Debian-based distros:</p>
                 <pre>sudo apt install python3-pip pandoc perl sed

zip-guide.rst

@@ -160,6 +160,25 @@ In general the conventions in the Zcash protocol specification SHOULD be followe
 If you find this difficult, don't worry too much about it in initial drafts; the
 ZIP editors will catch any inconsistencies in review.
 
+Notes and warnings
+------------------
+
+.. note::
+    "``.. note::``" in reStructuredText, or "``:::info``" (terminated by
+    "``:::``") in Markdown, can be used for an aside from the main text.
+
+    The rendering of notes is colourful and may be distracting, so they should
+    only be used for important points.
+
+.. warning::
+    "``.. warning::``" in reStructuredText, or "``:::warning``" (terminated by
+    "``:::``") in Markdown, can be used for warnings.
+
+    Warnings should be used very sparingly — for example to signal that a
+    entire specification, or part of it, may be inapplicable or could cause
+    significant interoperability or security problems. In most cases, a "MUST"
+    or "SHOULD" conformance requirement is more appropriate.
+
 Valid reStructuredText
 ----------------------