Merge branch 'main' into mbostock/page-loader

Author: mbostock

.github/workflows/deploy.yml

@@ -32,8 +32,6 @@ jobs:
             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 {} +
       - run: yarn build
       - run: yarn docs:build
       - name: Build example "api"

docs/config.md

@@ -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");
@@ -116,7 +116,7 @@ An array containing pages and sections. If not specified, it defaults to all Mar
 
 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/pull/1208" class="observablehq-version-badge" data-version="prerelease" title="Added in #1208"></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.
+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.
 
 For example, here **pages** specifies two sections and a total of four pages:
 
@@ -162,16 +162,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.
@@ -262,3 +252,15 @@ export default {
   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/contributing.md

@@ -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/data/dft-road-collisions.csv.sh

@@ -1,2 +1,2 @@
-curl -O -z docs/.observablehq/cache/dft-collisions.csv 'https://data.dft.gov.uk/road-accidents-safety-data/dft-road-casualty-statistics-collision-1979-latest-published-year.csv'
+test -f docs/.observablehq/cache/dft-collisions.csv || curl -o docs/.observablehq/cache/dft-collisions.csv 'https://data.dft.gov.uk/road-accidents-safety-data/dft-road-casualty-statistics-collision-1979-latest-published-year.csv'
 duckdb -c "COPY (SELECT longitude, latitude FROM read_csv_auto('docs/.observablehq/cache/dft-collisions.csv') WHERE accident_year = 2022) TO STDOUT WITH (FORMAT CSV);"

docs/deploying.md

@@ -26,7 +26,7 @@ The first time you deploy a project, you will be prompted to configure the proje
 
 When the deploy command finishes, it prints a link to observablehq.cloud where you can view your deployed project. If you choose *private* as the access level, that link will only be accessible to members of your Observable workspace. (You can invite people to your workspace by going to observablehq.com.) If you chose *public*, you can share your project link with anyone. You can change the access level of a project later [from your workspace projects page](https://observablehq.com/select-workspace?next=projects).
 
-<div class="note">The deploy command creates a file at <code>docs/.observablehq/deploy.json</code> with information on where to deploy the project. This file is required for automated deploys. You will need to commit this file to git to deploy via GitHub Actions. (If you have configured a source root besides <code>docs</code>, the file will be placed there instead.)</div>
+<div class="note">The deploy command creates a file at <code>.observablehq/deploy.json</code> under the source root (typically <code>src</code>) with information on where to deploy the project. This file is required for automated deploys. You will need to commit this file to git to deploy via GitHub Actions.</div>
 
 <div class="tip">To see more available options when deploying:<pre><code class="language-sh">npm run deploy -- --help</code></pre></div>
 
@@ -112,16 +112,14 @@ jobs:
       - id: cache-data
         uses: actions/cache@v4
         with:
-          path: docs/.observablehq/cache
-          key: data-${{ hashFiles('docs/data/*') }}-${{ steps.date.outputs.date }}
-      - if: steps.cache-data.outputs.cache-hit == 'true'
-        run: find docs/.observablehq/cache -type f -exec touch {} +
+          path: src/.observablehq/cache
+          key: data-${{ hashFiles('src/data/*') }}-${{ steps.date.outputs.date }}
       # ...
 ```
 
 This uses one cache per calendar day (in the `America/Los_Angeles` time zone). If you deploy multiple times in a day, the results of your data loaders will be reused on the second and subsequent runs. You can customize the `date` and `cache-data` steps to change the cadence of the caching. For example you could use `date +'%Y-%U'` to cache data for a week or `date +'%Y-%m-%dT%H` to cache it for only an hour.
 
-<div class="note">You’ll need to edit the paths above if you’ve configured a source root other than <code>docs</code>.</div>
+<div class="note">You’ll need to edit the paths above if you’ve configured a source root other than <code>src</code>.</div>
 
 ## Other hosting services
 

docs/files.md

@@ -4,7 +4,7 @@ keywords: file, fileattachment, attachment
 
 # Files
 
-Load files — whether static or generated dynamically by a [data loader](../loaders) — using the built-in `FileAttachment` function. This is available by default in Markdown, but you can import it explicitly like so:
+Load files — whether static or generated dynamically by a [data loader](./loaders) — using the built-in `FileAttachment` function. This is available by default in Markdown, but you can import it explicitly like so:
 
 ```js echo
 import {FileAttachment} from "npm:@observablehq/stdlib";
@@ -64,6 +64,7 @@ For missing files, `file.lastModified` is undefined. The `file.mimeType` is dete
 | [`file.arrow`][arrow]        | [`Table`][arrow-table]
 | [`file.blob`][binary]        | [`Blob`][blob]
 | [`file.csv`][csv]            | [`Array`][array]
+| [`file.dsv`][csv]            | [`Array`][array]
 | [`file.html`][markup]        | [`Document`][document]
 | [`file.image`][media]        | [`HTMLImageElement`][image]
 | [`file.json`][json]          | [`Array`][array], [`Object`][object], _etc._
@@ -210,11 +211,11 @@ display(total);
 
 ## Routing
 
-Attached files live in the source root (by default `docs`) alongside your Markdown pages. For example, say `index.md` has some JavaScript code that references `FileAttachment("quakes.csv")`:
+Attached files live in the source root (typically `src`) alongside your Markdown pages. For example, say `index.md` has some JavaScript code that references `FileAttachment("quakes.csv")`:
 
 ```ini
 .
-├─ docs
+├─ src
 │  ├─ index.md
 │  └─ quakes.csv
 └─ ...