Merge branch 'main' into fil/summary-table

Author: Fil

.github/workflows/deploy.yml

@@ -4,6 +4,8 @@ on:
   workflow_dispatch: {}
   push:
     branches: [main]
+  schedule:
+    - cron: "15 10 * * *"
 
 jobs:
   deploy:
@@ -19,59 +21,16 @@ jobs:
         with:
           node-version: 20
           cache: 'yarn'
-          cache-dependency-path: |
-            yarn.lock
-            'examples/*/yarn.lock'
       - run: yarn --frozen-lockfile
       - id: date
         run: echo "date=$(TZ=America/Los_Angeles date +'%Y-%m-%d')" >> $GITHUB_OUTPUT
       - id: cache-data
         uses: actions/cache@v4
         with:
-          path: |
-            docs/.observablehq/cache
-            examples/*/docs/.observablehq/cache
-          key: data-${{ hashFiles('docs/data/*', 'examples/*/docs/data/*') }}-${{ steps.date.outputs.date }}
-      - if: steps.cache-data.outputs.cache-hit == 'true'
-        run: find docs/.observablehq/cache examples/*/docs/.observablehq/cache -type f -exec touch {} +
+          path: docs/.observablehq/cache
+          key: data-${{ hashFiles('docs/data/*') }}-${{ steps.date.outputs.date }}
       - run: yarn build
       - run: yarn docs:build
-      - name: Build example "api"
-        run: yarn --frozen-lockfile && yarn build
-        working-directory: examples/api
-      - name: Build example "chess"
-        run: yarn --frozen-lockfile && yarn build
-        working-directory: examples/chess
-      - name: Build example "eia"
-        run: yarn --frozen-lockfile && yarn build
-        working-directory: examples/eia
-        env:
-          EIA_KEY: ${{ secrets.EIA_KEY }}
-      - name: Build example "google-analytics"
-        run: yarn --frozen-lockfile && yarn build
-        working-directory: examples/google-analytics
-        env:
-          GA_PROPERTY_ID: ${{ vars.GA_PROPERTY_ID }}
-          GA_CLIENT_EMAIL: ${{ secrets.GA_CLIENT_EMAIL }}
-          GA_PRIVATE_KEY: ${{ secrets.GA_PRIVATE_KEY }}
-      - name: Build example "hello-world"
-        run: yarn --frozen-lockfile && yarn build
-        working-directory: examples/hello-world
-      - name: Build example "mortgage-rates"
-        run: yarn --frozen-lockfile && yarn build
-        working-directory: examples/mortgage-rates
-      - name: Build example "penguin-classification"
-        run: |
-          python -m pip install --upgrade pip
-          pip install -r requirements.txt
-          yarn --frozen-lockfile && yarn build
-        working-directory: examples/penguin-classification
-      - name: Build example "plot"
-        run: yarn --frozen-lockfile && yarn build
-        working-directory: examples/plot
-        env:
-          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - run: mkdir docs/.observablehq/dist/examples && for i in examples/*; do if [ -d $i/dist ]; then mv -v $i/dist docs/.observablehq/dist/examples/$(basename $i); fi; done
       - uses: cloudflare/pages-action@1
         with:
           apiToken: ${{ secrets.CLOUDFLARE_API_TOKEN }}

README.md

@@ -1,5 +1,23 @@
 # Observable Framework
 
-- [Documentation](https://observablehq.com/framework/)
-- [Changelog](https://github.com/observablehq/framework/releases)
-- [Issues](https://github.com/observablehq/framework/issues)
+[**Observable Framework**](https://observablehq.com/framework/) is a free, [open-source](./LICENSE), static site generator for data apps, dashboards, reports, and more. Framework combines JavaScript on the front-end for interactive graphics with any language on the back-end for data analysis. Framework features [data loaders](https://observablehq.com/framework/loaders) that precompute static snapshots of data at build time for dashboards that load instantly.
+
+## Documentation 📚
+
+https://observablehq.com/framework/
+
+## Examples 🖼️
+
+https://github.com/observablehq/framework/tree/main/examples
+
+## Releases (changelog) 🚀
+
+https://github.com/observablehq/framework/releases
+
+## Getting help 🏠
+
+Please [open a discussion](https://github.com/observablehq/framework/discussions) if you’d like help. We also recommend [searching issues](https://github.com/observablehq/framework/issues). You can also ask on the [Observable forum](https://talk.observablehq.com/) or [Observable community Slack](https://observablehq.com/slack/join).
+
+## Contributing 🙏
+
+See [`CONTRIBUTING.md`](./CONTRIBUTING.md).

docs/assets/mortgage-rates-dark.webp

@@ -21,7 +21,7 @@ The following options are supported.
 
 ## root
 
-The path to the source root; defaults to `docs`.
+The path to the source root; defaults to `src`. (Prior to <a href="https://github.com/observablehq/framework/releases/tag/v1.7.0" class="observablehq-version-badge" data-version="^1.7.0" title="Added in 1.7.0"></a>, the default was `docs`.)
 
 ## output
 
@@ -67,9 +67,9 @@ See the [list of available themes](./themes) for more.
 
 ## style
 
-The path to a custom stylesheet, relative to the source root. This option takes precedence over the [theme option](#theme) (if any), providing more control by allowing you to remove or alter the default stylesheet and define a custom theme.
+The path to a custom stylesheet, relative to the source root (typically `src`). This option takes precedence over the [theme option](#theme) (if any), providing more control by allowing you to remove or alter the default stylesheet and define a custom theme.
 
-The custom stylesheet should typically import `observablehq:default.css` to build on the default styles. You can also import any of the built-in themes. For example, to create a stylesheet that builds up on the `air` theme, create a `custom-style.css` file in the `docs` folder, then set the style option to `custom-style.css`:
+The custom stylesheet should typically import `observablehq:default.css` to build on the default styles. You can also import any of the built-in themes. For example, to create a stylesheet that builds up on the `air` theme, create a `custom-style.css` file in the source root, then set the style option to `custom-style.css`:
 
 ```css
 @import url("observablehq:default.css");
@@ -114,7 +114,11 @@ Whether to show the sidebar. Defaults to true if **pages** is not empty.
 
 An array containing pages and sections. If not specified, it defaults to all Markdown files found in the source root in directory listing order.
 
-Both pages and sections have a **name**, which typically corresponds to the page’s title. The name gets displayed in the sidebar. Clicking on a page navigates to the corresponding **path**, which should start with a leading slash and be relative to the root; the path can also be specified as a full URL to navigate to an external site. Clicking on a section header opens or closes that section. Each section must specify an array of **pages**, and optionally whether the section is **open** by default. If **open** is not set, it defaults to true. If **open** is false, the section is closed unless the current page belongs to that section.
+Both pages and sections have a **name**, which typically corresponds to the page’s title. The name gets displayed in the sidebar. Clicking on a page navigates to the corresponding **path**, which should start with a leading slash and be relative to the root; the path can also be specified as a full URL to navigate to an external site. Each section must specify an array of **pages**.
+
+Sections may be **collapsible**. <a href="https://github.com/observablehq/framework/releases/tag/v1.6.0" class="observablehq-version-badge" data-version="^1.6.0" title="Added in 1.6.0"></a> If the **open** option is set, the **collapsible** option defaults to true; otherwise it defaults to false. If the section is not collapsible, the **open** option is ignored and the section is always open; otherwise, the **open** option defaults to true. When a section is collapsible, clicking on a section header opens or closes that section. A section will always be open if the current page belongs to that section.
+
+Pages and sections may also have a **pager** field <a href="https://github.com/observablehq/framework/pull/1306" class="observablehq-version-badge" data-version="prerelease" title="Added in #1306"></a> which specifies the name of the page group; this determines which pages are linked to via the previous and next pager buttons. If the **pager** field is not specified, it defaults the current section’s **pager** field, or to `main` for top-level pages and sections. (The home page is always in the `main` pager group.) The **pager** field can be also set to `null` to disable the pager on a specific page or section, causing adjacent pages to skip the page.
 
 For example, here **pages** specifies two sections and a total of four pages:
 
@@ -160,16 +164,6 @@ An HTML fragment to add to the header. Defaults to the empty string.
 
 An HTML fragment to add to the footer. Defaults to “Built with Observable.”
 
-## scripts
-
-Additional scripts to add to the head, such as for analytics. Unlike the **head** option, this allows you to reference a local script in the source root.
-
-```js run=false
-export default {
-  scripts: [{type: "module", async: true, src: "analytics.js"}]
-};
-```
-
 ## base
 
 The base path when serving the site. Currently this only affects the custom 404 page, if any.
@@ -251,13 +245,24 @@ export default {
 
 ## markdownIt <a href="https://github.com/observablehq/framework/releases/tag/v1.1.0" class="observablehq-version-badge" data-version="^1.1.0" title="Added in v1.1.0"></a>
 
-A hook for registering additional [markdown-it](https://github.com/markdown-it/markdown-it) plugins. For example, to use [markdown-it-footnote](https://github.com/markdown-it/markdown-it-footnote):
+A hook for registering additional [markdown-it](https://github.com/markdown-it/markdown-it) plugins. For example, to use [markdown-it-footnote](https://github.com/markdown-it/markdown-it-footnote), first install the plugin with either `npm add markdown-it-footnote` or `yarn add markdown-it-footnote`, then register it like so:
 
 ```js run=false
-import type MarkdownIt from "markdown-it";
 import MarkdownItFootnote from "markdown-it-footnote";
 
 export default {
-  markdownIt: (md: MarkdownIt) => md.use(MarkdownItFootnote);
+  markdownIt: (md) => md.use(MarkdownItFootnote)
 };
 ```
+
+## typographer <a href="https://github.com/observablehq/framework/releases/tag/v1.7.0" class="observablehq-version-badge" data-version="^1.7.0" title="Added in 1.7.0"></a>
+
+If true, enables simple typographic replacements in Markdown, such as replacing `(c)` with `©` and converting straight quotes to curly quotes. See also the [quotes](#quotes) option, which should be set for non-English languages if the **typographer** option is enabled. For the full list of replacements, see [markdown-it](https://github.com/markdown-it/markdown-it/blob/master/lib/rules_core/replacements.mjs). Defaults to false.
+
+## quotes <a href="https://github.com/observablehq/framework/releases/tag/v1.7.0" class="observablehq-version-badge" data-version="^1.7.0" title="Added in 1.7.0"></a>
+
+The set of replacements for straight double and single quotes used when the [**typographer** option](#typographer) is enabled. Defaults to `["“", "”", "‘", "’"]` which is suitable for English. For example, you can use `["«", "»", "„", "“"]` for Russian, `["„", "“", "‚", "‘"]` for German, and `["«\xa0", "\xa0»", "‹\xa0", "\xa0›"]` for French.
+
+## linkify <a href="https://github.com/observablehq/framework/releases/tag/v1.7.0" class="observablehq-version-badge" data-version="^1.7.0" title="Added in 1.7.0"></a>
+
+If true (the default), automatically convert URL-like text to links in Markdown.

docs/assets/mortgage-rates.webp

@@ -16,7 +16,7 @@ yarn dev
 
 Lastly visit <http://127.0.0.1:3000>.
 
-The local preview server restarts automatically if you edit any of the TypeScript files, though you may need to reload. The default page is [docs/index.md](https://github.com/observablehq/framework/blob/main/docs/index.md?plain=1); if you edit that file and save changes, the live preview in the browser will automatically update.
+The local preview server restarts automatically if you edit any of the TypeScript files, though you may need to reload. The default page is [`docs/index.md`](https://github.com/observablehq/framework/blob/main/docs/index.md?plain=1); if you edit that file and save changes, the live preview in the browser will automatically update.
 
 To generate the static site:
 

docs/assets/mosaic.webp

@@ -1,54 +1,3 @@
-# CSS: Card
+<meta http-equiv="refresh" content="0; url=../markdown#cards">
 
-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.
-
-```html echo
-<div class="card" style="max-width: 640px;">
-  <h2>It gets hotter during summer</h2>
-  <h3>And months have 28–31 days</h3>
-  ${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})}
-</div>
-```
-
-<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>
-
-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.
-
-```html echo
-<div class="grid grid-cols-2">
-  <div class="card">
-    <h2>Lorem ipsum</h2>
-    <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>
-    <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>
-  </div>
-  <div class="card" style="padding: 0;">
-    ${Inputs.table(industries)}
-  </div>
-</div>
-```
-
-<div class="tip">Remove the padding from a card if it contains only a table.</div>
-
-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:
-
-```js echo
-const industryInput = Inputs.select(industries.map((d) => d.industry), {unique: true, sort: true, label: "Industry:"});
-const industry = Generators.input(industryInput);
-```
-
-Then, insert the input into the card:
-
-```html echo
-<div class="card" style="display: flex; flex-direction: column; gap: 1rem;">
-  ${industryInput}
-  ${resize((width) => Plot.plot({
-    width,
-    y: {grid: true, label: "Unemployed (thousands)"},
-    marks: [
-      Plot.areaY(industries.filter((d) => d.industry === industry), {x: "date", y: "unemployed", fill: "var(--theme-foreground-muted)", curve: "step"}),
-      Plot.lineY(industries.filter((d) => d.industry === industry), {x: "date", y: "unemployed", curve: "step"}),
-      Plot.ruleY([0])
-    ]
-  }))}
-</div>
-```
+Moved to [Layout: Cards](../markdown#cards).

docs/javascript/bar.js renamed to docs/bar.js

@@ -1,88 +1,3 @@
-# CSS: Color
+<meta http-equiv="refresh" content="0; url=../themes#colors">
 
-The following custom properties are defined by the current [theme](../themes):
-
-<table>
-  <thead>
-    <tr>
-      <th>Name</th>
-      <th>Color</th>
-      <th>Description</th>
-    </tr>
-  </thead>
-  <tbody>
-    <tr>
-      <td><code>--theme-foreground</code></td>
-      <td><div style="background-color: var(--theme-foreground); width: 2rem; height: 1rem;"></div></td>
-      <td>page foreground color</td>
-    </tr>
-    <tr>
-      <td><code>--theme-background</code></td>
-      <td><div style="background-color: var(--theme-background); width: 2rem; height: 1rem;"></div></td>
-      <td>page background color</td>
-    </tr>
-    <tr>
-      <td><code>--theme-background-alt</code></td>
-      <td><div style="background-color: var(--theme-background-alt); width: 2rem; height: 1rem;"></div></td>
-      <td>block background color</td>
-    </tr>
-    <tr>
-      <td><code>--theme-foreground-alt</code></td>
-      <td><div style="background-color: var(--theme-foreground-alt); width: 2rem; height: 1rem;"></div></td>
-      <td>heading foreground color</td>
-    </tr>
-    <tr>
-      <td><code>--theme-foreground-muted</code></td>
-      <td><div style="background-color: var(--theme-foreground-muted); width: 2rem; height: 1rem;"></div></td>
-      <td>secondary text foreground color</td>
-    </tr>
-    <tr>
-      <td><code>--theme-foreground-faint</code></td>
-      <td><div style="background-color: var(--theme-foreground-faint); width: 2rem; height: 1rem;"></div></td>
-      <td>faint border color</td>
-    </tr>
-    <tr>
-      <td><code>--theme-foreground-fainter</code></td>
-      <td><div style="background-color: var(--theme-foreground-fainter); width: 2rem; height: 1rem;"></div></td>
-      <td>fainter border color</td>
-    </tr>
-    <tr>
-      <td><code>--theme-foreground-faintest</code></td>
-      <td><div style="background-color: var(--theme-foreground-faintest); width: 2rem; height: 1rem;"></div></td>
-      <td>faintest border color</td>
-    </tr>
-    <tr>
-      <td><code>--theme-foreground-focus</code></td>
-      <td><div style="background-color: var(--theme-foreground-focus); width: 2rem; height: 1rem;"></div></td>
-      <td>emphasis foreground color</td>
-    </tr>
-  </tbody>
-</table>
-
-You can use these properties anywhere you like. For example, to style a line chart to match the focus color:
-
-```js echo
-Plot.lineY(aapl, {x: "Date", y: "Close", stroke: "var(--theme-foreground-focus)"}).plot()
-```
-
-A handful of color classes are also provided:
-
-```html echo
-<div class="red">I am red text.</div>
-```
-
-```html echo
-<div class="yellow">I am yellow text.</div>
-```
-
-```html echo
-<div class="green">I am green text.</div>
-```
-
-```html echo
-<div class="blue">I am blue text.</div>
-```
-
-```html echo
-<div class="muted">I am muted text.</div>
-```
+Moved to [Themes: Colors](../themes#colors).