Skip to content

Commit d774917

Browse files
mbostockFil
andauthored
restructure & expand docs (#1187)
* checkpoint docs * restructure * checkpoint restructure * checkpoint * what is framework; note background * note margin-trim * more edits * more edits * more edits * more edits * projects page * more overview * more overview * more edits * more edits * more edits * more edits * more edits * more edits * more edits * more edits * more edits * more edits * more edits * back to files; more edits * back to files; more edits * more edits * more edits * more edits * more edits * self-host sample data * project-structure * reoder markdown * fix links * fix redirect * fix redirects * Apply suggestions from code review Co-authored-by: Philippe Rivière <[email protected]> * edits * more edits * Update docs/files.md Co-authored-by: Philippe Rivière <[email protected]> --------- Co-authored-by: Philippe Rivière <[email protected]>
1 parent c0fc544 commit d774917

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

58 files changed

+4007
-13200
lines changed

docs/assets/mortgage-rates-dark.webp

18.8 KB
Binary file not shown.

docs/assets/mortgage-rates.webp

19.2 KB
Binary file not shown.

docs/assets/mosaic.webp

82.8 KB
Binary file not shown.
File renamed without changes.

docs/css/card.md

Lines changed: 2 additions & 53 deletions
Original file line numberDiff line numberDiff line change
@@ -1,54 +1,3 @@
1-
# CSS: Card
1+
<meta http-equiv="refresh" content="0; url=../markdown#cards">
22

3-
The `card` class is used to group and delineate content. The `card` classes applies a background and border (with colors determined by the current [theme](../themes)). A card can have a title and subtitle using <code>h2</code> and <code>h3</code> elements, respectively.
4-
5-
```html echo
6-
<div class="card" style="max-width: 640px;">
7-
<h2>It gets hotter during summer</h2>
8-
<h3>And months have 28–31 days</h3>
9-
${Plot.cell(weather.slice(-365), {x: (d) => d.date.getUTCDate(), y: (d) => d.date.getUTCMonth(), fill: "temp_max", tip: true, inset: 0.5}).plot({marginTop: 0, height: 240, padding: 0})}
10-
</div>
11-
```
12-
13-
<div class="tip"><a href="../lib/plot">Observable Plot</a>’s <b>title</b> and <b>subtitle</b> options generate <code>h2</code> and <code>h3</code> elements, respectively, and so will inherit these card styles.</div>
14-
15-
Cards can be used on their own, but they most often exist in a [grid](./grid). Cards can contain whatever you like, including text, images, charts, tables, inputs, and more.
16-
17-
```html echo
18-
<div class="grid grid-cols-2">
19-
<div class="card">
20-
<h2>Lorem ipsum</h2>
21-
<p>Id ornare arcu odio ut sem nulla pharetra. Aliquet lectus proin nibh nisl condimentum id venenatis a. Feugiat sed lectus vestibulum mattis ullamcorper velit. Aliquet nec ullamcorper sit amet. Sit amet tellus cras adipiscing. Condimentum id venenatis a condimentum vitae. Semper eget duis at tellus. Ut faucibus pulvinar elementum integer enim.</p>
22-
<p>Et malesuada fames ac turpis. Integer vitae justo eget magna fermentum iaculis eu non diam. Aliquet risus feugiat in ante metus dictum at. Consectetur purus ut faucibus pulvinar.</p>
23-
</div>
24-
<div class="card" style="padding: 0;">
25-
${Inputs.table(industries)}
26-
</div>
27-
</div>
28-
```
29-
30-
<div class="tip">Remove the padding from a card if it contains only a table.</div>
31-
32-
To place an input inside a card, first declare a detached input as a [top-level variable](../javascript/reactivity#top-level-variables) and use [`Generators.input`](../lib/generators#inputelement) to expose its reactive value:
33-
34-
```js echo
35-
const industryInput = Inputs.select(industries.map((d) => d.industry), {unique: true, sort: true, label: "Industry:"});
36-
const industry = Generators.input(industryInput);
37-
```
38-
39-
Then, insert the input into the card:
40-
41-
```html echo
42-
<div class="card" style="display: flex; flex-direction: column; gap: 1rem;">
43-
${industryInput}
44-
${resize((width) => Plot.plot({
45-
width,
46-
y: {grid: true, label: "Unemployed (thousands)"},
47-
marks: [
48-
Plot.areaY(industries.filter((d) => d.industry === industry), {x: "date", y: "unemployed", fill: "var(--theme-foreground-muted)", curve: "step"}),
49-
Plot.lineY(industries.filter((d) => d.industry === industry), {x: "date", y: "unemployed", curve: "step"}),
50-
Plot.ruleY([0])
51-
]
52-
}))}
53-
</div>
54-
```
3+
Moved to [Layout: Cards](../markdown#cards).

docs/css/color.md

Lines changed: 2 additions & 87 deletions
Original file line numberDiff line numberDiff line change
@@ -1,88 +1,3 @@
1-
# CSS: Color
1+
<meta http-equiv="refresh" content="0; url=../themes#colors">
22

3-
The following custom properties are defined by the current [theme](../themes):
4-
5-
<table>
6-
<thead>
7-
<tr>
8-
<th>Name</th>
9-
<th>Color</th>
10-
<th>Description</th>
11-
</tr>
12-
</thead>
13-
<tbody>
14-
<tr>
15-
<td><code>--theme-foreground</code></td>
16-
<td><div style="background-color: var(--theme-foreground); width: 2rem; height: 1rem;"></div></td>
17-
<td>page foreground color</td>
18-
</tr>
19-
<tr>
20-
<td><code>--theme-background</code></td>
21-
<td><div style="background-color: var(--theme-background); width: 2rem; height: 1rem;"></div></td>
22-
<td>page background color</td>
23-
</tr>
24-
<tr>
25-
<td><code>--theme-background-alt</code></td>
26-
<td><div style="background-color: var(--theme-background-alt); width: 2rem; height: 1rem;"></div></td>
27-
<td>block background color</td>
28-
</tr>
29-
<tr>
30-
<td><code>--theme-foreground-alt</code></td>
31-
<td><div style="background-color: var(--theme-foreground-alt); width: 2rem; height: 1rem;"></div></td>
32-
<td>heading foreground color</td>
33-
</tr>
34-
<tr>
35-
<td><code>--theme-foreground-muted</code></td>
36-
<td><div style="background-color: var(--theme-foreground-muted); width: 2rem; height: 1rem;"></div></td>
37-
<td>secondary text foreground color</td>
38-
</tr>
39-
<tr>
40-
<td><code>--theme-foreground-faint</code></td>
41-
<td><div style="background-color: var(--theme-foreground-faint); width: 2rem; height: 1rem;"></div></td>
42-
<td>faint border color</td>
43-
</tr>
44-
<tr>
45-
<td><code>--theme-foreground-fainter</code></td>
46-
<td><div style="background-color: var(--theme-foreground-fainter); width: 2rem; height: 1rem;"></div></td>
47-
<td>fainter border color</td>
48-
</tr>
49-
<tr>
50-
<td><code>--theme-foreground-faintest</code></td>
51-
<td><div style="background-color: var(--theme-foreground-faintest); width: 2rem; height: 1rem;"></div></td>
52-
<td>faintest border color</td>
53-
</tr>
54-
<tr>
55-
<td><code>--theme-foreground-focus</code></td>
56-
<td><div style="background-color: var(--theme-foreground-focus); width: 2rem; height: 1rem;"></div></td>
57-
<td>emphasis foreground color</td>
58-
</tr>
59-
</tbody>
60-
</table>
61-
62-
You can use these properties anywhere you like. For example, to style a line chart to match the focus color:
63-
64-
```js echo
65-
Plot.lineY(aapl, {x: "Date", y: "Close", stroke: "var(--theme-foreground-focus)"}).plot()
66-
```
67-
68-
A handful of color classes are also provided:
69-
70-
```html echo
71-
<div class="red">I am red text.</div>
72-
```
73-
74-
```html echo
75-
<div class="yellow">I am yellow text.</div>
76-
```
77-
78-
```html echo
79-
<div class="green">I am green text.</div>
80-
```
81-
82-
```html echo
83-
<div class="blue">I am blue text.</div>
84-
```
85-
86-
```html echo
87-
<div class="muted">I am muted text.</div>
88-
```
3+
Moved to [Themes: Colors](../themes#colors).

docs/css/grid.md

Lines changed: 2 additions & 81 deletions
Original file line numberDiff line numberDiff line change
@@ -1,82 +1,3 @@
1-
# CSS: Grid
1+
<meta http-equiv="refresh" content="0; url=../markdown#grids">
22

3-
The `grid` class declares a [CSS grid](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_grid_layout) container. The `grid` class is designed to pair with the [`card` class](./card) and the [`dashboard` theme](../themes) for dashboard layout.
4-
5-
```html echo
6-
<div class="grid grid-cols-4">
7-
<div class="card"><h1>A</h1></div>
8-
<div class="card"><h1>B</h1></div>
9-
<div class="card"><h1>C</h1></div>
10-
<div class="card"><h1>D</h1></div>
11-
</div>
12-
```
13-
14-
Grids have a single column by default, but you can declare two, three, or four columns using the `grid-cols-2`, `grid-cols-3`, or `grid-cols-4` class.
15-
16-
The built-in `grid` class is automatically responsive: in narrow windows, the number of columns is automatically reduced. The four-column grid can be reduced to two or one columns, while the three- and two-column grid can be reduced to one column. (If you want more columns or more control over the grid layout, you can always write custom styles.)
17-
18-
<div class="tip">To see the responsive grid layout, resize the window or collapse the sidebar on the left. You can also zoom to change the effective window size.</div>
19-
20-
With multi-column and multi-row grids, you can use the `grid-colspan-*` and `grid-rowspan-*` classes to have cells that span columns and rows, respectively.
21-
22-
```html echo
23-
<div class="grid grid-cols-2">
24-
<div class="card"><h1>A</h1>1 × 1</div>
25-
<div class="card grid-rowspan-2"><h1>B</h1>1 × 2</div>
26-
<div class="card"><h1>C</h1>1 × 1</div>
27-
<div class="card grid-colspan-2"><h1>D</h1>2 × 1</div>
28-
</div>
29-
```
30-
31-
By default, the `grid` uses `grid-auto-rows: 1fr`, which means that every row of the grid has the same height. The “rhythm” of equal-height rows is often desirable.
32-
33-
```html echo
34-
<div class="grid grid-cols-2">
35-
<div class="card">Call me Ishmael.</div>
36-
<div class="card">Some years ago—never mind how long precisely—having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world.</div>
37-
<div class="card">It is a way I have of driving off the spleen and regulating the circulation.</div>
38-
</div>
39-
```
40-
41-
On the other hand, forcing all rows to the same height can waste space, since the height of all rows is based on the tallest content across rows. To have variable-height rows instead, you can either set [`grid-auto-rows`](https://developer.mozilla.org/en-US/docs/Web/CSS/grid-auto-rows) on the grid container:
42-
43-
```html echo
44-
<div class="grid grid-cols-2" style="grid-auto-rows: auto;">
45-
<div class="card">Call me Ishmael.</div>
46-
<div class="card">Some years ago—never mind how long precisely—having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world.</div>
47-
<div class="card">It is a way I have of driving off the spleen and regulating the circulation.</div>
48-
</div>
49-
```
50-
51-
Or break your grid into multiple grids:
52-
53-
```html echo
54-
<div class="grid grid-cols-2">
55-
<div class="card">Call me Ishmael.</div>
56-
<div class="card">Some years ago—never mind how long precisely—having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world.</div>
57-
</div>
58-
<div class="grid grid-cols-2">
59-
<div class="card">It is a way I have of driving off the spleen and regulating the circulation.</div>
60-
</div>
61-
```
62-
63-
The `card` class is not required to use `grid`. If you use `grid` by itself, you’ll get the same layout but without the card aesthetics.
64-
65-
```html echo
66-
<div class="grid grid-cols-2">
67-
<div>Some years ago—never mind how long precisely—having little or no money in my purse, and nothing particular to interest me on shore, I thought I would sail about a little and see the watery part of the world.</div>
68-
<div class="card">Call me Ishmael.</div>
69-
</div>
70-
```
71-
72-
Use the `resize` helper to re-render content when the container resizes.
73-
74-
```html echo
75-
<div class="grid grid-cols-4">
76-
<div class="card">
77-
${resize((width) => `This card is ${width}px wide.`)}
78-
</div>
79-
</div>
80-
```
81-
82-
See [Responsive display](../javascript/display#responsive-display) for more.
3+
Moved to [Markdown: Grids](../markdown#grids).

docs/css/note.md

Lines changed: 2 additions & 54 deletions
Original file line numberDiff line numberDiff line change
@@ -1,55 +1,3 @@
1-
# CSS: Note
1+
<meta http-equiv="refresh" content="0; url=../markdown#notes">
22

3-
The `note`, `tip`, `warning`, and `caution` classes can be used to insert labeled notes (also known as callouts) into prose. These are intended to emphasize important information that could otherwise be overlooked.
4-
5-
<div class="note">This is a note.</div>
6-
7-
```html run=false
8-
<div class="note">This is a note.</div>
9-
```
10-
11-
<div class="tip">This is a tip.</div>
12-
13-
```html run=false
14-
<div class="tip">This is a tip.</div>
15-
```
16-
17-
<div class="warning">This is a warning.</div>
18-
19-
```html run=false
20-
<div class="warning">This is a warning.</div>
21-
```
22-
23-
<div class="caution">This is a caution.</div>
24-
25-
```html run=false
26-
<div class="caution">This is a caution.</div>
27-
```
28-
29-
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.)
30-
31-
<div class="tip">
32-
<p>This is a <i>styled</i> tip using <small>HTML</small>.</p>
33-
</div>
34-
35-
```html run=false
36-
<div class="tip">
37-
<p>This is a <i>styled</i> tip using <small>HTML</small>.</p>
38-
</div>
39-
```
40-
41-
You can override the note’s label using the `label` attribute.
42-
43-
<div class="warning" label="⚠️ Danger ⚠️">No lifeguard on duty. Swim at your own risk!</div>
44-
45-
```html run=false
46-
<div class="warning" label="⚠️ Danger ⚠️">No lifeguard on duty. Swim at your own risk!</div>
47-
```
48-
49-
You can disable the label entirely with an empty `label` attribute.
50-
51-
<div class="note" label>This note has no label.</div>
52-
53-
```html run=false
54-
<div class="note" label>This note has no label.</div>
55-
```
3+
Moved to [Layout: Notes](../markdown#notes).

docs/data/alphabet.csv

Lines changed: 27 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,27 @@
1+
letter,frequency
2+
E,0.12702
3+
T,0.09056
4+
A,0.08167
5+
O,0.07507
6+
I,0.06966
7+
N,0.06749
8+
S,0.06327
9+
H,0.06094
10+
R,0.05987
11+
D,0.04253
12+
L,0.04025
13+
C,0.02782
14+
U,0.02758
15+
M,0.02406
16+
W,0.0236
17+
F,0.02288
18+
G,0.02015
19+
Y,0.01974
20+
P,0.01929
21+
B,0.01492
22+
V,0.00978
23+
K,0.00772
24+
J,0.00153
25+
X,0.0015
26+
Q,0.00095
27+
Z,0.00074

0 commit comments

Comments
 (0)