change default source root from docs to src (#1253)

* Update config.ts

change default root from docs to pages

closes #752
supersedes main...mythmon/240325/default-root-pages

* move templates and examples

* fix tests

* update documentation

* move docs to pages

* gitignore pages

* update deploy.yml github workflow

* default src; use docs here

* replace many more instances of “docs”

* remove pointless await

* default to docs, if present

* tweak warning

* prettier

* delete spurious file

* explicit root; config.js

---------

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

Author: Fil

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/pull/1253" class="observablehq-version-badge" data-version="prerelease" title="Added in #1253"></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");

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/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,14 +112,14 @@ jobs:
       - id: cache-data
         uses: actions/cache@v4
         with:
-          path: docs/.observablehq/cache
-          key: data-${{ hashFiles('docs/data/*') }}-${{ steps.date.outputs.date }}
+          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

@@ -211,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
 └─ ...

docs/getting-started.md

@@ -167,14 +167,14 @@ Now visit <http://127.0.0.1:3000> in your browser, which should look like:
     <source srcset="./getting-started/hello-framework-dark.webp" media="(prefers-color-scheme: dark)">
     <img loading="lazy" src="./getting-started/hello-framework.webp" style="aspect-ratio: 3248 / 2112;">
   </picture>
-  <figcaption>The default home page (<code>docs/index.md</code>) after creating a new project.</figcaption>
+  <figcaption>The default home page (<code>src/index.md</code>) after creating a new project.</figcaption>
 </figure>
 
 ### Test live preview
 
 Live preview means that as you save changes, your in-browser preview updates instantly. Live preview applies to Markdown pages, imported JavaScript modules (so-called *hot module replacement*), data loaders, and file attachments. This feature is implemented by the preview server watching files and pushing changes to the browser over a socket.
 
-To experience live preview, open <code>docs/index.md</code> in your preferred text editor — below we show Visual Studio Code — and position your browser window so that you can see your editor and browser side-by-side. If you then replace the text “Hello, Observable Framework” with “Hi, Mom!” and save, you should see:
+To experience live preview, open <code>src/index.md</code> in your preferred text editor — below we show Visual Studio Code — and position your browser window so that you can see your editor and browser side-by-side. If you then replace the text “Hello, Observable Framework” with “Hi, Mom!” and save, you should see:
 
 <figure class="wide">
   <picture>
@@ -186,7 +186,7 @@ To experience live preview, open <code>docs/index.md</code> in your preferred te
 
 ### Create a new page
 
-Now let’s add a page for our weather dashboard. Create a new file `docs/weather.md` and paste in the following snippet:
+Now let’s add a page for our weather dashboard. Create a new file `src/weather.md` and paste in the following snippet:
 
 ````md run=false
 # Weather report
@@ -216,7 +216,7 @@ As evidenced by the code <code class="language-js">1 + 2</code> rendered as <cod
 
 Next, let’s load some data. The [National Weather Service (NWS)](https://www.weather.gov/documentation/services-web-api) provides an excellent and free API for local weather data within the United States. We’ll use the `/points/{latitude},{longitude}` endpoint to get metadata for the closest grid point to the given location, and then fetch the corresponding hourly forecast.
 
-Create a new file <code>docs/data/forecast.json.js</code> and paste in the following snippet:
+Create a new file <code>src/data/forecast.json.js</code> and paste in the following snippet:
 
 <pre><code class="language-js">const longitude = ${html`<span class="hljs-number">${longitude.toFixed(2)}</span>`};
 const latitude = ${html`<span class="hljs-number">${latitude.toFixed(2)}</span>`};
@@ -280,13 +280,13 @@ Your data loader should look like this:
 
 If you like, you can run your data loader manually in the terminal:
 
-<pre data-copy>node docs/data/forecast.json.js</pre>
+<pre data-copy>node src/data/forecast.json.js</pre>
 
 If this barfs a bunch of JSON in the terminal, it’s working as intended. 😅 Normally you don’t run data loaders by hand — Framework runs them automatically, as needed — but data loaders are “just” programs so you can run them manually if you want. Conversely, any executable or shell script that runs on your machine and outputs something to stdout can be a data loader!
 
 ### File attachments
 
-Framework uses [file-based routing](./loaders#routing) for data loaders: the data loader <code>forecast.json.js</code> serves the file <code>forecast.json</code>. To load this file from <code>docs<span class="wbr">/</span>weather.md</code> we use the relative path <code>./data<span class="wbr">/</span>forecast.json</code>. In effect, data loaders are simply a naming convention for generating “static” files — a big advantage of which is that you can edit a data loader and the changes immediately propagate to the live preview without needing a reload.
+Framework uses [file-based routing](./loaders#routing) for data loaders: the data loader <code>forecast.json.js</code> serves the file <code>forecast.json</code>. To load this file from <code>src<span class="wbr">/</span>weather.md</code> we use the relative path <code>./data<span class="wbr">/</span>forecast.json</code>. In effect, data loaders are simply a naming convention for generating “static” files — a big advantage of which is that you can edit a data loader and the changes immediately propagate to the live preview without needing a reload.
 
 To load a file in JavaScript, use the built-in [`FileAttachment`](./files). In `weather.md`, replace the contents of the JavaScript code block (the parts inside the triple backticks <code>```</code>) with the following code:
 
@@ -508,7 +508,7 @@ When deploy completes, Framework will show your project’s URL on observablehq.
 <span class="muted">└</span>  <span class="muted">Deployed project now visible at <u>https://example.observablehq.cloud/hello-framework/</u></span>
 </pre>
 
-<div class="tip">Your deploy configuration is saved to <code>docs<span class="wbr">/</span>.observablehq<span class="wbr">/</span>deploy.json</code>. When collaborating on a project, you should commit this file to git so your collaborators don’t have to separately configure deploy.</div>
+<div class="tip">Your deploy configuration is saved to <code>src<span class="wbr">/</span>.observablehq<span class="wbr">/</span>deploy.json</code>. When collaborating on a project, you should commit this file to git so your collaborators don’t have to separately configure deploy.</div>
 
 ### Self hosting
 

docs/imports.md

@@ -67,7 +67,7 @@ If you do not specify an entry point, the default entry point is determined by t
 
 Framework downloads `npm:` imports from jsDelivr during preview and build. This improves performance, security, and stability of your built site by removing runtime dependencies on external sites.
 
-Downloads from npm are cached in `.observablehq/cache/_npm` within your [source root](./config#root) (`docs` by default). An imported module is downloaded from jsDelivr only if it is not already in the cache. You can clear the cache and restart the server to re-fetch the latest versions of libraries from npm.
+Downloads from npm are cached in `.observablehq/cache/_npm` within your [source root](./config#root) (typically `src`). An imported module is downloaded from jsDelivr only if it is not already in the cache. You can clear the cache and restart the server to re-fetch the latest versions of libraries from npm.
 
 Self-hosting of `npm:` imports applies to transitive static and [dynamic imports](#dynamic-imports). In addition to downloading modules, Framework downloads supporting files as needed for [recommended libraries](#implicit-imports) and [`import.meta.resolve`](#import-resolutions). For example, [DuckDB](./lib/duckdb) needs WebAssembly modules, and [KaTeX](./lib/tex) needs a stylesheet and fonts. For dynamic imports and `import.meta.resolve`, Framework is only able to self-host import specifiers that are static string literals.
 
@@ -97,7 +97,7 @@ import mime from "mime/lite";
 
 Unlike `npm:` imports, Node imports do not support semver ranges: the imported version is determined by what is installed in your `node_modules` directory. Use your package manager (_e.g._, edit your `package.json` and run `npm install`, or run `npm update`) to change which version is imported.
 
-Imports from `node_modules` are cached in `.observablehq/cache/_node` within your [source root](./config#root) (`docs` by default). You shouldn’t need to clear this cache as it is automatically managed, but feel free to clear it you like.
+Imports from `node_modules` are cached in `.observablehq/cache/_node` within your [source root](./config#root) (typically `src`). You shouldn’t need to clear this cache as it is automatically managed, but feel free to clear it you like.
 
 ## Local imports
 
@@ -249,7 +249,7 @@ Imported modules are copied to the output root (`dist` by default) during build,
 
 ```ini
 .
-├─ docs
+├─ src
 │  ├─ chart.js
 │  └─ index.md
 └─ ...

docs/loaders.md

@@ -139,7 +139,7 @@ Like with any other file, files from generated archives are live in preview (ref
 
 ## Routing
 
-Data loaders live in the source root (typically `docs`) alongside your other source files. When a file is referenced from JavaScript via `FileAttachment`, if the file does not exist, Framework will look for a file of the same name with a double extension to see if there is a corresponding data loader. By default, the following second extensions are checked, in order, with the corresponding language and interpreter:
+Data loaders live in the source root (typically `src`) alongside your other source files. When a file is referenced from JavaScript via `FileAttachment`, if the file does not exist, Framework will look for a file of the same name with a double extension to see if there is a corresponding data loader. By default, the following second extensions are checked, in order, with the corresponding language and interpreter:
 
 - `.js` - JavaScript (`node`)
 - `.ts` - TypeScript (`tsx`)
@@ -185,7 +185,7 @@ You can then run the `observable preview` or `observable build` commands as usua
 
 </div>
 
-Data loaders are run in the same working directory in which you run the `observable build` or `observable preview` command, which is typically the project root. In Node, you can access the current working directory by calling `process.cwd()`, and the data loader’s source location with [`import.meta.url`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import.meta). To compute the path of a file relative to the data loader source (rather than relative to the current working directory), use [`import.meta.resolve`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import.meta/resolve). For example, a data loader in `docs/summary.txt.js` could read the file `docs/table.txt` as:
+Data loaders are run in the same working directory in which you run the `observable build` or `observable preview` command, which is typically the project root. In Node, you can access the current working directory by calling `process.cwd()`, and the data loader’s source location with [`import.meta.url`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import.meta). To compute the path of a file relative to the data loader source (rather than relative to the current working directory), use [`import.meta.resolve`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Operators/import.meta/resolve). For example, a data loader in `src/summary.txt.js` could read the file `src/table.txt` as:
 
 ```js run=false
 import {readFile} from "node:fs/promises";
@@ -197,7 +197,7 @@ const table = await readFile(fileURLToPath(import.meta.resolve("./table.txt")),
 Executable (`.exe`) data loaders are run directly and must have the executable bit set. This is typically done via [`chmod`](https://en.wikipedia.org/wiki/Chmod). For example:
 
 ```sh
-chmod +x docs/quakes.csv.exe
+chmod +x src/quakes.csv.exe
 ```
 
 While a `.exe` data loader may be any binary executable (_e.g.,_ compiled from C), it is often convenient to specify another interpreter using a [shebang](<https://en.wikipedia.org/wiki/Shebang_(Unix)>). For example, to write a data loader in Perl:
@@ -220,7 +220,7 @@ Data loaders generate files at build time that live alongside other [static file
 
 ```ini
 .
-├─ docs
+├─ src
 │  ├─ index.md
 │  └─ quakes.json.sh
 └─ ...
@@ -249,7 +249,7 @@ As another example, say you have a `quakes.zip` archive that includes yearly fil
 
 ```ini
 .
-├─ docs
+├─ src
 │  ├─ index.md
 │  └─ quakes.zip
 └─ ...
@@ -269,11 +269,11 @@ Becomes this output:
 └─ ...
 ```
 
-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 (`docs`) for data loaders.
+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.
 
 ## Caching
 
-When a data loader runs successfully, its output is saved to a cache which lives in `.observablehq/cache` within the source root (by default `docs`).
+When a data loader runs successfully, its output is saved to a cache which lives in `.observablehq/cache` within the source root (typically `src`).
 
 During preview, Framework considers the cache “fresh” if the modification time of the cached output is newer than the modification time of the corresponding data loader source. If you edit a data loader or update its modification time with `touch`, the cache is invalidated; when previewing a page that uses the data loader, the preview server will detect that the data loader was modified and automatically run it, pushing the new data down to the client and re-evaluating any referencing code — no reload required!
 
@@ -282,13 +282,13 @@ During build, Framework ignores modification times and only runs a data loader i
 To purge the data loader cache and force all data loaders to run on the next build, delete the entire cache. For example:
 
 ```sh
-rm -rf docs/.observablehq/cache
+rm -rf src/.observablehq/cache
 ```
 
-To force a specific data loader to run on the next build instead, delete its corresponding output from the cache. For example, to rebuild `docs/quakes.csv`:
+To force a specific data loader to run on the next build instead, delete its corresponding output from the cache. For example, to rebuild `src/quakes.csv`:
 
 ```sh
-rm -f docs/.observablehq/cache/quakes.csv
+rm -f src/.observablehq/cache/quakes.csv
 ```
 
 See [Automated deploys: Caching](./deploying#caching) for more on caching during CI.