note, tip, warning, caution (#598)

Author: mbostock

docs/contributing.md

@@ -40,7 +40,9 @@ yarn test:coverage
 
 ## Releasing
 
-(Note: This documentation is for Observable maintainers.) To release a new version of the CLI, first update the [package.json](https://github.com/observablehq/cli/blob/main/package.json) file by following the standard process for committing code changes:
+<div class="note">These instructions are intended for Observable staff.</div>
+
+To release a new version of the CLI, first update the [package.json](https://github.com/observablehq/cli/blob/main/package.json) file by following the standard process for committing code changes:
 
 1. Create a new branch.
 2. Edit the `version` field in the [package.json](https://github.com/observablehq/cli/blob/main/package.json) file as desired.

docs/layout/note.md

@@ -0,0 +1,55 @@
+# Layout: Note
+
+The `note`, `tip`, `warning`, and `caution` classes can be used to insert labeled notes into prose. These are intended to emphasize important information that could otherwise be overlooked.
+
+<div class="note">This is a note.</div>
+
+```html run=false
+<div class="note">This is a note.</div>
+```
+
+<div class="tip">This is a tip.</div>
+
+```html run=false
+<div class="tip">This is a tip.</div>
+```
+
+<div class="warning">This is a warning.</div>
+
+```html run=false
+<div class="warning">This is a warning.</div>
+```
+
+<div class="caution">This is a caution.</div>
+
+```html run=false
+<div class="caution">This is a caution.</div>
+```
+
+Markdown is not supported within HTML, so if you want rich formatting or links within a note, you must write it as HTML. (In the future, we may add support for notes within Markdown.)
+
+<div class="tip">
+  <p>This is a <i>styled</i> tip using <small>HTML</small>.</p>
+</div>
+
+```html run=false
+<div class="tip">
+  <p>This is a <i>styled</i> tip using <small>HTML</small>.</p>
+</div>
+```
+
+You can override the note’s label using the `label` attribute.
+
+<div class="warning" label="⚠️ Danger ⚠️">No lifeguard on duty. Swim at your own risk!</div>
+
+```html run=false
+<div class="warning" label="⚠️ Danger ⚠️">No lifeguard on duty. Swim at your own risk!</div>
+```
+
+You can disable the label entirely with an empty `label` attribute.
+
+<div class="note" label>This note has no label.</div>
+
+```html run=false
+<div class="note" label>This note has no label.</div>
+```

docs/layout/resize.md

@@ -57,4 +57,4 @@ html`<div class="grid grid-cols-2" style="grid-auto-rows: 300px;">
 </div>
 ```
 
-Note: If you are using `resize` with both `width` and `height` and see nothing rendered, it may be because your parent container does not have its own height specified.
+<div class="tip">If you are using <code>resize</code> with both <code>width</code> and <code>height</code> and see nothing rendered, it may be because your parent container does not have its own height specified.</div>

docs/lib/vega-lite.md

@@ -53,4 +53,5 @@ vl.render({
 })
 ```
 
-Note: when loading data from a file as above, use [`FileAttachment`](../javascript/files) so that referenced files are included on [build](../getting-started#build).
+<div class="tip">When loading data from a file as above, use <a href="../javascript/files"><code>FileAttachment</code></a> so that referenced files are included on <a href="../getting-started#build">build</a>.</div>
+

docs/markdown.md

@@ -2,7 +2,7 @@
 
 Markdown in the Observable CLI follows the [CommonMark spec](https://spec.commonmark.org/) and is powered by [markdown-it](https://github.com/markdown-it/markdown-it).  We also feature [live JavaScript](./javascript) as either [fenced code blocks](./javascript#fenced-code-blocks) (<code>```js</code>) or [inline expressions](./javascript#inline-expressions) (<code>$\{…}</code>), and [HTML in Markdown](#html), and [front matter](#front-matter) for page-level configuration. If you don’t already know Markdown, please see [GitHub’s guide to Markdown](https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax) for an introduction.
 
-_Note: The Observable CLI currently deviates from CommonMark in how blank lines are handled in HTML; see below. This is a limitation of our parser needed for incremental update during preview._
+<div class="note">The Observable CLI currently deviates from CommonMark in how blank lines are handled in HTML; see below. This is a limitation of our parser needed for incremental update during preview.</div>
 
 Here are a few examples of Markdown content to get you started.
 
@@ -23,7 +23,7 @@ toc: false
 ### A third-level heading
 ```
 
-Note: a second-level heading (`##`) immediately following a first-level heading (`#`) is styled specially as a subtitle.
+<div class="note">A second-level heading (<code>##</code>) immediately following a first-level heading (<code>#</code>) is styled specially as a subtitle.</div>
 
 ## Styling
 

observablehq.config.ts

@@ -25,8 +25,9 @@ export default {
       name: "Layout",
       open: false,
       pages: [
-        {name: "Grid", path: "/layout/grid"},
         {name: "Card", path: "/layout/card"},
+        {name: "Grid", path: "/layout/grid"},
+        {name: "Note", path: "/layout/note"},
         {name: "Resize", path: "/layout/resize"}
       ]
     },

src/style/default.css

@@ -1,6 +1,7 @@
 @import url("./global.css");
 @import url("./layout.css");
 @import url("./grid.css");
+@import url("./note.css");
 @import url("./card.css");
 @import url("./inspector.css");
 @import url("./plot.css");

src/style/note.css

@@ -0,0 +1,55 @@
+.note,
+.tip,
+.warning,
+.caution {
+  border-left: solid 1px var(--theme-foreground-fainter);
+  padding: 0 2rem;
+  margin: 1rem 0;
+  box-sizing: border-box;
+  max-width: 640px;
+}
+
+.note::before,
+.tip::before,
+.warning::before,
+.caution::before {
+  content: "Note";
+  display: block;
+  margin-bottom: 1rem;
+  font-weight: 700;
+  color: var(--theme-foreground-muted);
+}
+
+.tip {
+  border-left-color: var(--theme-green);
+}
+
+.tip::before {
+  content: "Tip";
+  color: var(--theme-green);
+}
+
+.warning {
+  border-left-color: var(--theme-yellow);
+}
+
+.warning::before {
+  content: "Warning";
+  color: var(--theme-yellow);
+}
+
+.caution {
+  border-left-color: var(--theme-red);
+}
+
+.caution::before {
+  content: "Caution";
+  color: var(--theme-red);
+}
+
+.note[label]::before,
+.tip[label]::before,
+.warning[label]::before,
+.caution[label]::before {
+  content: attr(label);
+}