project vs. app (#1621)

* project vs. app

* an app

* use project here

* fix some ellipses

* app configuration

Author: mbostock

docs/config.md

@@ -1,10 +1,10 @@
 # Configuration
 
-A `observablehq.config.js` (or `observablehq.config.ts`) file located in the project root allows configuration of your project. For example, a site might use a config file to set the project’s title and the sidebar contents:
+A `observablehq.config.js` (or `observablehq.config.ts`) file located in the project root allows configuration of your app. For example, you might use a config file to set the app’s title and sidebar contents:
 
 ```js run=false
 export default {
-  title: "My awesome project",
+  title: "My awesome app",
   pages: [
     {name: "Getting ever more awesome", path: "/getting-awesome"},
     {name: "Being totally awesome", path: "/being-awesome"},
@@ -104,7 +104,7 @@ In this case, the path to the stylesheet is resolved relative to the page’s Ma
 
 ## title
 
-The project’s title. If specified, this text is used for the link to the home page in the sidebar, and to complement the titles of the webpages. For instance, a page titled “Sales” in a project titled “ACME, Inc.” will display “Sales | ACME, Inc.” in the browser’s title bar. If not specified, the home page link will appear as “Home” in the sidebar, and page titles will be shown as-is.
+The app’s title. If specified, this text is used for the link to the home page in the sidebar, and to complement the titles of the webpages. For instance, a page titled “Sales” in an app titled “ACME, Inc.” will display “Sales | ACME, Inc.” in the browser’s title bar. If not specified, the home page link will appear as “Home” in the sidebar, and page titles will be shown as-is.
 
 ## sidebar
 
@@ -147,7 +147,7 @@ Sections may be **collapsible**. <a href="https://github.com/observablehq/framew
 
 Pages and sections may also have a **pager** field <a href="https://github.com/observablehq/framework/releases/tag/v1.8.0" class="observablehq-version-badge" data-version="^1.8.0" title="Added in 1.8.0"></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.
 
-Projects can have “unlisted” pages that are not referenced in **pages**. These pages can still be linked from other pages or visited directly, but they won’t be listed in the sidebar or linked to via the previous & next pager links.
+Apps can have “unlisted” pages that are not referenced in **pages**. These pages can still be linked from other pages or visited directly, but they won’t be listed in the sidebar or linked to via the previous & next pager links.
 
 The pages list should _not_ include the home page (`/`) as this is automatically linked at the top of the sidebar. We also do not recommend listing the same page multiple times (say with different query parameters or anchor fragments), as this causes the previous & next pager links to cycle.
 
@@ -202,7 +202,7 @@ If **show** is not set, it defaults to true. If **label** is not set, it default
 
 If shown, the table of contents enumerates the second-level headings (H2 elements, such as `## Section name`) on the right-hand side of the page. The currently-shown section is highlighted in the table of contents.
 
-The table of contents configuration can also be set in the page’s YAML front matter. The page-level configuration takes precedence over the project-level configuration. For example, to disable the table of contents on a particular page:
+The table of contents configuration can also be set in the page’s YAML front matter. The page-level configuration takes precedence over the app-level configuration. For example, to disable the table of contents on a particular page:
 
 ```yaml
 ---
@@ -212,7 +212,7 @@ toc: false
 
 ## search
 
-If true, enable [search](./search) on the project; defaults to false. The **search** option may also be specified as an object with an **index** method <a href="https://github.com/observablehq/framework/releases/tag/v1.9.0" class="observablehq-version-badge" data-version="^1.9.0" title="Added in 1.9.0"></a>, in which case additional results can be added to the search index. Each result is specified as:
+If true, enable [search](./search); defaults to false. The **search** option may also be specified as an object with an **index** method <a href="https://github.com/observablehq/framework/releases/tag/v1.9.0" class="observablehq-version-badge" data-version="^1.9.0" title="Added in 1.9.0"></a>, in which case additional results can be added to the search index. Each result is specified as:
 
 ```ts run=false
 interface SearchResult {

docs/data-loaders.md

@@ -167,7 +167,7 @@ To use an interpreted data loader (anything other than `.exe`), the correspondin
 
 <div class="tip" id="venv">
 
-You can use a virtual environment in Python, such as [venv](https://docs.python.org/3/tutorial/venv.html) or  [uv](https://github.com/astral-sh/uv), to install libraries locally to the project. This is useful when working in multiple projects, and when collaborating; you can also track dependencies in a `requirements.txt` file.
+You can use a virtual environment in Python, such as [venv](https://docs.python.org/3/tutorial/venv.html) or [uv](https://github.com/astral-sh/uv), to install libraries locally to the project. This is useful when working in multiple projects, and when collaborating; you can also track dependencies in a `requirements.txt` file.
 
 To create a virtual environment with venv:
 
@@ -241,7 +241,7 @@ Data loaders generate files at build time that live alongside other [static file
 ├─ src
 │  ├─ index.md
 │  └─ quakes.json.sh
-└─ ...
+└─ …
 ```
 
 Where `quakes.json.sh` is:
@@ -258,9 +258,9 @@ This will produce the following output root:
 │  ├─ _file
 │  │  └─ quakes.99da78d9.json
 │  ├─ _observablehq
-│  │  └─ ... # additional assets for serving the site
+│  │  └─ … # additional assets
 │  └─ index.html
-└─ ...
+└─ …
 ```
 
 As another example, say you have a `quakes.zip` archive that includes yearly files for observed earthquakes. If you reference `FileAttachment("quakes/2021.csv")`, Framework will pull the `2021.csv` from `quakes.zip`. So this source root:
@@ -270,7 +270,7 @@ As another example, say you have a `quakes.zip` archive that includes yearly fil
 ├─ src
 │  ├─ index.md
 │  └─ quakes.zip
-└─ ...
+└─ …
 ```
 
 Becomes this output:
@@ -282,9 +282,9 @@ Becomes this output:
 │  │  └─ quakes
 │  │     └─ 2021.e5f2eb94.csv
 │  ├─ _observablehq
-│  │  └─ ... # additional assets for serving the site
+│  │  └─ … # additional assets
 │  └─ index.html
-└─ ...
+└─ …
 ```
 
 A data loader is only run during build if its corresponding output file is referenced in at least one page. Framework does not scour the source root (typically `src`) for data loaders.

docs/deploying.md

@@ -1,16 +1,16 @@
 # Deploying
 
-You can host your built Framework project on any static site hosting service, or self-host it with any static site server. This guide covers deploying to [Observable](https://observablehq.com), which is the easiest way to host your Framework project as support is built-in. We’ll also cover setting up automated deploys with GitHub Actions.
+You can host your built Framework app on any static site hosting service, or self-host it with any static site server. This guide covers deploying to [Observable](https://observablehq.com), which is the easiest way to host your Framework app as support is built-in. We’ll also cover setting up automated deploys with GitHub Actions.
 
 <div class="tip">
 
-If you don’t already have a project ready to deploy, create one by following our [Getting started guide](./getting-started).
+If you don’t already have an app ready to deploy, create one by following our [Getting started guide](./getting-started).
 
 </div>
 
 ## Manual deploys
 
-First, make sure that your project builds without error:
+First, make sure that your app builds without error:
 
 ```sh
 npm run build
@@ -22,15 +22,15 @@ Once that is done you can deploy to Observable:
 npm run deploy
 ```
 
-The first time you deploy a project, you will be prompted to configure the project’s _slug_ (which determines its URL), access level, and other details. If you aren’t yet signed-in to Observable, you will also be prompted to sign-in.
+The first time you deploy an app, you will be prompted to configure the app’s _slug_ (which determines its URL), access level, and other details. If you aren’t yet signed-in to Observable, you will also be prompted to sign-in.
 
-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).
+When the deploy command finishes, it prints a link to observablehq.cloud where you can view your deployed app. 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 app link with anyone. You can change the access level of an app later [from your workspace projects <!-- TODO apps --> page](https://observablehq.com/select-workspace?next=projects).
 
 <div class="tip">To see more available options when deploying:<pre><code class="language-sh">npm run deploy -- --help</code></pre></div>
 
 ## Deploy configuration
 
-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 allows you to re-deploy a project without having to repeat where you want the project to live on Observable.
+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 app. This file allows you to re-deploy an app without having to repeat where you want the app to live on Observable.
 
 The contents of the deploy config file look like this:
 
@@ -44,13 +44,13 @@ The contents of the deploy config file look like this:
 
 A deploy config file is required for automated deploys. You will need to commit this file to git to deploy via GitHub Actions.
 
-To store the deploy config file somewhere else, use the `--deploy-config` argument. For example, to create a “staging” deploy to share early versions of you project, you could use a `deploy-staging.json` like so:
+To store the deploy config file somewhere else, use the `--deploy-config` argument. For example, to create a “staging” deploy to share early versions of your app, you could use a `deploy-staging.json` like so:
 
 ```sh
 npm run deploy -- --deploy-config=src/.observablehq/deploy-staging.json
 ```
 
-If the specified config file does not yet exist, you will again be prompted to choose or create a new project; the resulting configuration will then be saved to the specified file. You can re-deploy to staging by passing the same `--deploy-config` argument; or you can deploy to “production” by not specifying the `--deploy-config` argument to use the default deploy config.
+If the specified config file does not yet exist, you will again be prompted to choose or create a new app; the resulting configuration will then be saved to the specified file. You can re-deploy to staging by passing the same `--deploy-config` argument; or you can deploy to “production” by not specifying the `--deploy-config` argument to use the default deploy config.
 
 ## Automated deploys
 
@@ -94,13 +94,13 @@ To create an API key:
 
 1. Open the [API Key settings](https://observablehq.com/select-workspace?next=api-keys-settings) for your Observable workspace.
 2. Click **New API Key**.
-3. Check the **Deploy new versions of projects** checkbox.
+3. Check the **Deploy new versions of projects** checkbox. <!-- TODO apps -->
 4. Give your key a description, such as “Deploy via GitHub Actions”.
 5. Click **Create API Key**.
 
 <div class="caution">
 
-The token you create is the equivalent of a password giving write access to your hosted project. **Do not commit it to git** or share it with anyone you don’t trust. If you accidentally expose your key, you can go back to your settings to immediately revoke it (and create a new key).
+The token you create is the equivalent of a password giving write access to your hosted app. **Do not commit it to git** or share it with anyone you don’t trust. If you accidentally expose your key, you can go back to your settings to immediately revoke it (and create a new key).
 
 </div>
 
@@ -118,7 +118,7 @@ To create a GitHub secret, in a new window:
 6. In the **Secret** field, paste the API key you created on Observable.
 7. Click **Add secret**.
 
-After you’ve performed these steps, the `deploy.yml` above will automatically build and deploy your project once per day (to keep your data up-to-date), as well as whenever you push a new version of the code to your repository (so you can make changes at any time).
+After you’ve performed these steps, the `deploy.yml` above will automatically build and deploy your app once per day (to keep your data up-to-date), as well as whenever you push a new version of the code to your repository (so you can make changes at any time).
 
 ### Caching
 
@@ -128,15 +128,15 @@ If some of your data loaders take a long time to run, or simply don’t need to
 jobs:
   deploy:
     steps:
-      # ...
+      # …
       - id: date
         run: echo "date=$(TZ=America/Los_Angeles date +'%Y-%m-%d')" >> $GITHUB_OUTPUT
       - id: cache-data
         uses: actions/cache@v4
         with:
           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.
@@ -145,7 +145,7 @@ This uses one cache per calendar day (in the `America/Los_Angeles` time zone). I
 
 ## Other hosting services
 
-Observable Framework builds a set of static files that can be hosted by any static site hosting services. To build your project, run:
+Observable Framework builds a set of static files that can be hosted by any static site hosting services. To build your app, run:
 
 ```sh
 npm run build

docs/files.md

@@ -221,7 +221,7 @@ Attached files live in the source root (typically `src`) alongside your Markdown
 ├─ src
 │  ├─ index.md
 │  └─ quakes.csv
-└─ ...
+└─ …
 ```
 
 On build, any files referenced by `FileAttachment` will automatically be copied to the `_file` folder under the output root (`dist`), here resulting in:
@@ -232,9 +232,9 @@ On build, any files referenced by `FileAttachment` will automatically be copied
 │  ├─ _file
 │  │  └─ quakes.e5f2eb94.csv
 │  ├─ _observablehq
-│  │  └─ ... # additional assets for serving the site
+│  │  └─ … # additional assets
 │  └─ index.html
-└─ ...
+└─ …
 ```
 
 `FileAttachment` references are automatically rewritten during build; for example, a reference to `quakes.csv` might be replaced with `_file/quakes.e5f2eb94.csv`. (As with imports, file names are given a content hash, here `e5f2eb94`, to improve performance.) Only the files you reference statically are copied to the output root (`dist`), so nothing extra or unused is included in the built site.