lots of new links (#1487)

* new links

* what is plot links

* yet another histogram

* a bit more links (300!)

* why-plot links

* plots links

* transforms links

* facet links

* legend links

* curve link

* formats links, fix Invalid date

* shorthand links

* scales links

* remove duplicate

* restore blank lines

---------

Co-authored-by: Mike Bostock <[email protected]>

Author: Fil

docs/features/curves.md

@@ -41,7 +41,7 @@ A **curve** defines how to turn a discrete representation of a line as a sequenc
   </label>
 </p>
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-curve-option
 ```js-vue
 Plot.plot({
   marks: [

docs/features/facets.md

@@ -25,7 +25,7 @@ Faceting partitions data by ordinal or categorical value and then repeats a plot
 
 For example, below we recreate the Trellis display (“reminiscent of garden trelliswork”) of [Becker *et al.*](https://hci.stanford.edu/courses/cs448b/papers/becker-trellis-jcgs.pdf) using the dot’s **fy** channel to declare vertical↕︎ facets, showing the yields of several varieties of barley across several sites for the years <span :style="{borderBottom: `solid 2px ${d3.schemeTableau10[0]}`}">1931</span> and <span :style="{borderBottom: `solid 2px ${d3.schemeTableau10[1]}`}">1932</span>.
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-trellis
 ```js
 Plot.plot({
   height: 800,
@@ -59,7 +59,7 @@ Use the [frame mark](../marks/frame.md) for stronger visual separation of facets
 
 The chart above reveals a likely data collection error: the years appear to be reversed for the Morris site as it is the only site where the yields in <span :style="{borderBottom: `solid 2px ${d3.schemeTableau10[1]}`}">1932</span> were higher than in <span :style="{borderBottom: `solid 2px ${d3.schemeTableau10[0]}`}">1931</span>. The anomaly in Morris is more obvious if we use directed arrows to show the year-over-year change. The [group transform](../transforms/group.md) groups the observations by site and variety to compute the change.
 
-:::plot defer
+:::plot defer https://observablehq.com/@observablehq/plot-trellis-anomaly
 ```js
 Plot.plot({
   height: 800,
@@ -94,7 +94,7 @@ Here the sort order has changed slightly: the *y* and *fy* domains are sorted by
 
 Faceting requires ordinal or categorical data because there are a discrete number of facets; the associated *fx* and *fy* scales are [band scales](./scales.md#discrete-position). Quantitative or temporal data can be made ordinal by binning, say using [Math.floor](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Math/floor). Or, use the [**interval** scale option](../transforms/interval.md) on the *fx* or *fy* scale. Below, we produce a [box plot](../marks/box.md) of the weights (in kilograms) of Olympic athletes, faceted by height binned at a 10cm (0.1 meter) interval.
 
-:::plot defer
+:::plot defer https://observablehq.com/@observablehq/plot-olympians-box-plot
 ```js
 Plot.plot({
   fy: {
@@ -116,7 +116,7 @@ If you are interested in automatic faceting for quantitative data, please upvote
 
 When both **fx** and **fy** channels are specified, two-dimensional faceting results, as in the faceted scatterplot of penguin culmen measurements below. The horizontal↔︎ facet shows sex (with the rightmost column representing penguins whose *sex* field is null, indicating missing data), while the vertical↕︎ facet shows species.
 
-:::plot defer
+:::plot defer https://observablehq.com/@observablehq/plot-two-dimensional-faceting
 ```js
 Plot.plot({
   grid: true,
@@ -137,7 +137,7 @@ Plot.plot({
 
 You can mix-and-match faceted and non-faceted marks within the same plot. The non-faceted marks will be repeated across all facets. This is useful for decoration marks, such as a [frame](../marks/frame.md), and also for context: below, the entire population of penguins is repeated in each facet as small gray dots, making it easier to see how each facet compares to the whole.
 
-:::plot defer
+:::plot defer https://observablehq.com/@observablehq/plot-non-faceted-marks
 ```js
 Plot.plot({
   grid: true,
@@ -206,7 +206,7 @@ This example uses an [immediately-invoked function expression (IIFE)](https://de
 
 The above chart also demonstrates faceted annotations, using a [text mark](../marks/text.md) to label the facet in lieu of facet axes. Below, we apply a single text annotation to the *Adelie* facet by setting the **fy** channel to a single-element array parallel to the data.
 
-:::plot defer
+:::plot defer https://observablehq.com/@observablehq/plot-annotated-facets
 ```js
 Plot.plot({
   marginLeft: 60,

docs/features/formats.md

@@ -12,14 +12,14 @@ These helper functions are provided for convenience as a **tickFormat** option f
 ## formatIsoDate(*date*)
 
 ```js
-Plot.formatIsoDate(new Date("2020-01-01T00:00.000Z")) // "2020-01-01"
+Plot.formatIsoDate(new Date("2020-01-01T00:00:00.000Z")) // "2020-01-01"
 ```
 
 Given a *date*, returns the shortest equivalent ISO 8601 UTC string. If the given *date* is not valid, returns `"Invalid Date"`. See [isoformat](https://github.com/mbostock/isoformat).
 
 ## formatWeekday(*locale*, *format*)
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-format-helpers
 ```js
 Plot.textX(d3.range(7)).plot({x: {tickFormat: Plot.formatWeekday()}})
 ```
@@ -33,7 +33,7 @@ Returns a function that formats a given week day number (from 0 = Sunday to 6 =
 
 ## formatMonth(*locale*, *format*)
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-format-helpers
 ```js
 Plot.textX(d3.range(12)).plot({x: {tickFormat: Plot.formatMonth(), ticks: 12}})
 ```

docs/features/legends.md

@@ -28,7 +28,7 @@ onMounted(() => {
 
 Plot can generate **legends** for *color*, *opacity*, and *symbol* [scales](./scales.md). For example, the scatterplot below of body measurements of Olympic athletes includes a legend for its *color* scale, allowing the meaning of color to be interpreted by the reader. (The axes similarly document the meaning of the *x* and *y* position scales.)
 
-:::plot defer
+:::plot defer https://observablehq.com/@observablehq/plot-olympians-scatterplot
 ```js
 Plot.plot({
   color: {legend: true},
@@ -41,7 +41,7 @@ Plot.plot({
 
 The legend above is a *swatches* legend because the *color* scale is *ordinal* (with a *categorical* scheme). When the *color* scale is continuous, a *ramp* legend with a smooth gradient is generated instead. The plot below of global average surface temperature ([GISTEMP](https://data.giss.nasa.gov/gistemp/)) uses a *diverging* *color* scale to indicate the deviation from the 1951–1980 average in degrees Celsius.
 
-:::plot defer
+:::plot defer https://observablehq.com/@observablehq/plot-colored-scatterplot
 ```js
 Plot.plot({
   color: {
@@ -78,7 +78,7 @@ Plot does not yet generate legends for the *r* (radius) scale or the *length* sc
 
 If the **legend** [scale option](./scales.md#scale-options) is true, the default legend will be produced for the scale; otherwise, the meaning of the **legend** option depends on the scale: for quantitative color scales, it defaults to *ramp* but may be set to *swatches* for a discrete scale (most commonly for *threshold* color scales); for *ordinal* *color* scales and *symbol* scales, only the *swatches* value is supported.
 
-<!-- TODO Describe the color and opacity options, and demo the symbol legend with a redundant color encoding. -->
+<!-- TODO Describe the color and opacity options. -->
 
 Categorical and ordinal color legends are rendered as swatches, unless the **legend** option is set to *ramp*. The swatches can be configured with the following options:
 

docs/features/plots.md

@@ -25,7 +25,7 @@ onMounted(() => {
 
 To render a **plot** in Observable Plot, call [plot](#plot-options) (typically as `Plot.plot`), passing in the desired *options*. This function returns an SVG or HTML figure element.
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-hello-world
 ```js
 Plot.plot({
   marks: [
@@ -70,7 +70,7 @@ Rather than baking data into JavaScript, use [JSON](https://en.wikipedia.org/wik
 
 To use data with Plot, pass the data as the first argument to the mark constructor. We can then assign columns of data such as *Date* and *Close* to visual properties of the mark (or “channels”) such as horizontal↔︎ position **x** and vertical↕︎ position **y**.
 
-:::plot defer
+:::plot defer https://observablehq.com/@observablehq/plot-first-line-chart
 ```js
 Plot.plot({
   marks: [
@@ -82,7 +82,7 @@ Plot.plot({
 
 A plot can have multiple marks, and each mark has its own data. For example, say we had a similar table `goog` representing the daily price of Google stock for the same period. Below, the <span style="border-bottom: solid 2px var(--vp-c-red);">red</span> line represents Google stock, while the <span style="border-bottom: solid 2px var(--vp-c-blue);">blue</span> line represents Apple stock.
 
-:::plot defer
+:::plot defer https://observablehq.com/@observablehq/plot-layered-marks
 ```js
 Plot.plot({
   marks: [
@@ -100,7 +100,7 @@ When comparing the performance of different stocks, we typically want to normali
 
 Alternatively, the tables can be combined, say with a *Symbol* column to distinguish AAPL from GOOG. This allows the use of a categorical *color* scale and legend.
 
-:::plot defer
+:::plot defer https://observablehq.com/@observablehq/plot-stocks-multiline-chart
 ```js
 Plot.plot({
   color: {legend: true},
@@ -120,7 +120,7 @@ Each mark may be a nested array of marks, allowing composition. Marks may also b
 
 Marks are drawn in the given order, with the last mark drawn on top. For example, below <span style="border-bottom: solid 2px var(--vp-c-green);">green</span> bars are drawn on top of <span style="border-bottom: solid 2px;">{{dark ? "white" : "black"}}</span> bars.
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-marks-z-order
 ```js
 Plot.plot({
   x: {padding: 0.4},
@@ -157,7 +157,7 @@ The **aspectRatio** option, if not null, computes a default **height** such that
   </label>
 </p>
 
-:::plot defer
+:::plot defer https://observablehq.com/@observablehq/plot-intro-to-aspectratio
 ```js
 Plot.plot({
   grid: true,
@@ -184,7 +184,7 @@ Unitless numbers ([quirky lengths](https://www.w3.org/TR/css-values-4/#deprecate
 
 If a **caption** is specified, Plot.plot wraps the generated SVG element in an HTML figure element with a figcaption, returning the figure. To specify an HTML caption, the caption can be specified as an HTML element, say using the [`html` tagged template literal](http://github.com/observablehq/htl); otherwise, the specified string represents text that will be escaped as needed.
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-caption
 ```js
 Plot.plot({
   caption: "Figure 1. A chart with a caption.",

docs/features/scales.md

@@ -40,7 +40,7 @@ onMounted(() => {
 
 When visualizing this data with a [line](../marks/line.md), the *x* scale is responsible for mapping dates to horizontal↔︎ positions. For example, 1880-01-01 might be mapped to *x* = 40 (on the left) and 2016-12-01 might be mapped to *x* = 620 (on the right). Likewise, the *y* scale maps temperature anomalies to vertical↕︎ positions.
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-scales-intro
 ```js
 Plot.lineY(gistemp, {x: "Date", y: "Anomaly"}).plot()
 ```
@@ -69,7 +69,7 @@ const maxAnomaly = d3.max(gistemp, (d) => d.Anomaly);
 
 Scales aren’t limited to horizontal and vertical position. They can also output to color, radius, length, opacity, and more. For example if we switch to a [rule](../marks/rule.md) and use the **stroke** channel instead of **y**, we get a one-dimensional heatmap:
 
-:::plot defer
+:::plot defer https://observablehq.com/@observablehq/plot-scales-intro
 ```js
 Plot.ruleX(gistemp, {x: "Date", stroke: "Anomaly"}).plot()
 ```
@@ -86,7 +86,7 @@ function color(anomaly) {
 
 Within a given [plot](./plots.md), marks share scales. For example, if a plot has two line marks, such as the lines below visualizing the daily closing price of <span style="border-bottom: solid 2px var(--vp-c-red);">Google</span> and <span style="border-bottom: solid 2px var(--vp-c-blue);">Apple</span> stock, both share the same *x* and *y* scales for a consistent encoding.
 
-:::plot defer
+:::plot defer https://observablehq.com/@observablehq/plot-layered-marks
 ```js
 Plot.plot({
   marks: [
@@ -118,23 +118,23 @@ Let’s look at some examples to make this less abstract.
 
 The domain of a quantitative scale is a continuous extent [*min*, *max*] where *min* and *max* are numbers, such as temperatures. Below, the first domain value (*x* = 0) corresponds to the left side of the plot while the second (*x* = 100) corresponds to the right side.
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-continuous-scales
 ```js
 Plot.plot({x: {domain: [0, 100], grid: true}})
 ```
 :::
 
 Flipping the domain reverses the scale so that +*x* points ←left instead of right→.
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-continuous-scales
 ```js
 Plot.plot({x: {domain: [100, 0], grid: true}})
 ```
 :::
 
 Alternatively, use the **reverse** option; this is convenient when the domain is implied from data rather than specified explicitly. (We’ll cover implied domains in more detail in the *inference* section below.)
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-continuous-scales
 ```js
 Plot.plot({x: {domain: [0, 100], reverse: true, grid: true}})
 ```
@@ -144,7 +144,7 @@ If the domain is dates, Plot will default to a UTC scale. This is a linear scale
 
 <!-- Plot doesn’t parse dates; convert your strings to [Date](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date) instances with [d3.utcParse](https://github.com/d3/d3-time-format#utcParse) or [d3.autoType](https://github.com/d3/d3-dsv#autoType). -->
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-continuous-scales
 ```js
 Plot.plot({x: {domain: [new Date("2021-01-01"), new Date("2022-01-01")], grid: true}})
 ```
@@ -156,61 +156,61 @@ We are working on better multi-line ticks for time scales; please upvote [#1285]
 
 To force a UTC scale, say when the data is milliseconds since UNIX epoch rather than Date instances, pass *utc* as the **type** option. Though we recommend coercing strings and numbers to more specific types when you load data, rather than relying on scales to do it.
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-continuous-scales
 ```js
 Plot.plot({x: {type: "utc", domain: [1609459200000, 1640995200000], grid: true}})
 ```
 :::
 
 If the scale **type** is *time*, the ticks will be in local time rather than UTC.
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-continuous-scales
 ```js
 Plot.plot({x: {type: "time", domain: [new Date(2021, 0, 1), new Date(2022, 0, 1)], grid: true}})
 ```
 :::
 
 When plotting values that vary widely, such as the luminosity of stars in an [HR diagram](https://observablehq.com/@mbostock/hertzsprung-russell-diagram), a *log* scale may improve readability. Log scales default to base-10 ticks with SI-prefix notation.
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-continuous-scales
 ```js
 Plot.plot({x: {type: "log", domain: [1e0, 1e5], grid: true}})
 ```
 :::
 
 If you prefer conventional notation, you can specify the **tickFormat** option to change the behavior of the axis. The **tickFormat** option can either be a [d3.format](https://github.com/d3/d3-format) string or a function that takes a tick value and returns the corresponding string. Note, however, that this may result in overlapping text.
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-continuous-scales
 ```js
 Plot.plot({x: {type: "log", domain: [1e0, 1e5], tickFormat: ",", grid: true}})
 ```
 :::
 
 Log scales also support a **base** option, say for powers of two. This does not affect the scale’s encoding, but it does change where ticks are shown.
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-continuous-scales
 ```js
 Plot.plot({x: {type: "log", base: 2, domain: [1e0, 1e4], ticks: 20, grid: true}})
 ```
 :::
 
 The domain of a log scale cannot include (or cross) zero; for this, consider a [bi-symmetric log](https://github.com/d3/d3-scale#symlog-scales) scale instead.
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-continuous-scales
 ```js
 Plot.plot({x: {type: "symlog", domain: [-10, 10], grid: true}})
 ```
 :::
 
 Power scales and square-root scales are also supported. The *pow* scale supports the **exponent** option, which defaults to 1 (for a linear scale).
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-continuous-scales
 ```js
 Plot.plot({x: {type: "sqrt", domain: [0, 100], grid: true}})
 ```
 :::
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-continuous-scales
 ```js
 Plot.plot({x: {type: "pow", exponent: 1 / 3, domain: [0, 100], grid: true}})
 ```
@@ -224,15 +224,15 @@ Sadly, not all data is continuous: some data is merely ordinal, such as t-shirt
 
 A *point* scale divides space into uniformly-spaced discrete values. It is commonly used for scatterplots (a [dot mark](../marks/dot.md)) of ordinal data. It is the default scale type for ordinal data on the *x* and *y* scale.
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-discrete-scales
 ```js
 Plot.plot({x: {type: "point", domain: "ABCDEFGHIJ", grid: true}})
 ```
 :::
 
 A band scale divides space into uniformly-spaced and -sized discrete intervals. It is commonly used for bar charts (bar marks). To show the bands below, we use a [cell](../marks/cell.md) instead of a [grid](../marks/grid.md).
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-discrete-scales
 ```js
 Plot
   .cell("ABCDEFGHIJ", {x: Plot.identity, stroke: "currentColor", strokeOpacity: 0.1})
@@ -255,7 +255,7 @@ While *point* and *band* scales appear visually similar when only the grid is vi
   </label>
 </p>
 
-:::plot hidden
+:::plot hidden https://observablehq.com/@observablehq/plot-discrete-scales
 ```js
 Plot.plot({
   grid: true,
@@ -273,7 +273,7 @@ Plot.plot({
 ```
 :::
 
-:::plot hidden
+:::plot hidden https://observablehq.com/@observablehq/plot-discrete-scales
 ```js
 Plot.plot({
   grid: true,
@@ -434,7 +434,7 @@ Plot.plot({
 
 Below we again show observed global surface temperatures. The reversed *BuRd* color scheme is used since <span :style="{borderBottom: `solid 2px ${d3.interpolateRdBu(0.9)}`}">blue</span> and <span :style="{borderBottom: `solid 2px ${d3.interpolateRdBu(0.1)}`}">red</span> are semantically associated with cold and hot, respectively.
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-colored-scatterplot
 ```js
 Plot.plot({
   grid: true,
@@ -537,7 +537,7 @@ But wait, there’s more! 😅 Plot has *opacity*, *r*, *symbol*, and *length* s
   </label>
 </p>
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-radius-scale-range
 ```js
 Plot.plot({
   r: {range: [0, radius]},
@@ -568,7 +568,7 @@ All position scales (*x*, *y*, *fx*, and *fy*) have implicit automatic ranges ba
 
 The **transform** scale option allows you to apply a function to all values before they are passed through the scale. This is convenient for transforming a scale’s data, say to convert to thousands or between temperature units.
 
-:::plot defer
+:::plot defer https://observablehq.com/@observablehq/plot-fahrenheit-to-celsius-scale-transform
 ```js{5}
 Plot.plot({
   y: {
@@ -586,7 +586,7 @@ Plot.plot({
 
 The **percent** scale option is shorthand for a **transform** that multiplies values by 100; it also adds a percent symbol (%) to the default label.
 
-:::plot
+:::plot https://observablehq.com/@observablehq/plot-percent-scale-transform
 ```js{2}
 Plot.plot({
   y: {percent: true}, // convert proportion [0, 1] to percent [0, 100]