Merge branch 'main' into fil/save-search-query

.eslintignore

@@ -1,2 +1,3 @@
+test/build
 test/input
 test/output

.github/workflows/deploy.yml

@@ -35,6 +35,7 @@ jobs:
       - 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"
         run: yarn --frozen-lockfile && yarn build
         working-directory: examples/api
@@ -70,17 +71,11 @@ jobs:
         working-directory: examples/plot
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-      - run: mkdir dist/examples && for i in examples/*; do if [ -d $i/dist ]; then mv -v $i/dist dist/examples/$(basename $i); fi; done
+      - 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 }}
           accountId: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
           projectName: framework
-          directory: dist
+          directory: docs/.observablehq/dist
           gitHubToken: ${{ secrets.GITHUB_TOKEN }}
-      # TODO: This doesn't include the examples. How can we fix that?
-      # TODO: Re-enable deploy to Observable
-      # - name: Deploy to Observable
-      #   run: yarn deploy -m "$(git log -1 --pretty=%s)"
-      #   env:
-      #     OBSERVABLE_TOKEN: ${{ secrets.OBSERVABLE_API_TOKEN }}

.github/workflows/publish.yml

@@ -1,6 +1,7 @@
 name: Publish
 
 on:
+  workflow_dispatch: {}
   release:
     types: [published]
 

.github/workflows/test.yml

@@ -21,7 +21,7 @@ jobs:
           node-version: ${{ matrix.version }}
           cache: yarn
       - run: yarn --frozen-lockfile
-      - run: yarn c8 --check-coverage -x src/**/*.d.ts -x src/preview.ts -x src/observableApiConfig.ts -x src/client -x src/convert.ts --lines 80 --per-file yarn test:mocha
+      - run: yarn test:coverage
       - run: yarn test:tsc
       - run: |
           echo ::add-matcher::.github/eslint.json

.gitignore

@@ -1,11 +1,13 @@
-.env
-.DS_Store
 **/.observablehq/cache/
-coverage/
-docs/themes.md
-docs/theme/*.md
-dist/
+.DS_Store
+.env
+/coverage/
+/dist/
+/docs/.observablehq/dist/
+/docs/theme/*.md
+/docs/themes.md
+/test/build/
+/test/output/**/*-changed.*
+/test/output/build/**/*-changed/
 node_modules/
-test/output/**/*-changed.*
-test/output/build/**/*-changed/
 yarn-error.log

build.js

@@ -0,0 +1,24 @@
+import {parseArgs} from "node:util";
+import {build} from "esbuild";
+import {glob} from "glob";
+
+const {values, positionals} = parseArgs({
+  allowPositionals: true,
+  options: {
+    outdir: {type: "string", default: "build"},
+    outbase: {type: "string"},
+    ignore: {type: "string", multiple: true},
+    sourcemap: {type: "boolean"}
+  }
+});
+
+await build({
+  entryPoints: await glob(positionals, {ignore: values.ignore}),
+  define: {"process.env.npm_package_version": `"${process.env.npm_package_version}"`},
+  outdir: values.outdir,
+  outbase: values.outbase,
+  platform: "node",
+  sourcemap: values.sourcemap ? "linked" : false,
+  format: "esm",
+  logLevel: "info"
+});

docs/config.md

@@ -195,3 +195,16 @@ toc: false
 ## search
 
 Whether to enable [search](./search) on the project; defaults to false.
+
+## markdownIt
+
+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):
+
+```js run=false
+import type MarkdownIt from "markdown-it";
+import MarkdownItFootnote from "markdown-it-footnote";
+
+export default {
+  markdownIt: (md: MarkdownIt) => md.use(MarkdownItFootnote);
+};
+```

docs/contributing.md

@@ -21,13 +21,13 @@ The local preview server restarts automatically if you edit any of the TypeScrip
 To generate the static site:
 
 ```sh
-yarn build
+yarn docs:build
 ```
 
-This creates the `dist` folder. View the site using your preferred web server, such as:
+This creates the `docs/.observablehq/dist` folder. View the site using your preferred web server, such as:
 
 ```sh
-http-server dist
+http-server docs/.observablehq/dist
 ```
 
 This documentation site is built on GitHub using Observable Framework; see the [deploy workflow](https://github.com/observablehq/framework/blob/main/.github/workflows/deploy.yml). Please open a pull request if you’d like to contribute. Contributors are expected to follow our [code of conduct](https://github.com/observablehq/.github/blob/master/CODE_OF_CONDUCT.md). 🙏

docs/getting-started.md

@@ -84,12 +84,10 @@ These are just first steps. You can continue to develop projects after publishin
 Framework includes a helper script (`observable create`) for creating new projects. After a few quick prompts — where to create the project, your preferred package manager, *etc.* — it will stamp out a fresh project from a template.
 
 <div class="tip">
-  <p>Framework is a <a href="https://nodejs.org/">Node.js</a> application published to npm. You must have <a href="https://nodejs.org/en/download">Node.js 20.6 or later</a> installed before you can install Framework. Framework is a command-line interface (CLI) and runs in the terminal.</p>
+  <p>Framework is a <a href="https://nodejs.org/">Node.js</a> application published to npm. You must have <a href="https://nodejs.org/en/download">Node.js 18 or later</a> installed before you can install Framework. Framework is a command-line interface (CLI) and runs in the terminal.</p>
   <p>If you run into difficulty following this tutorial, we’re happy to help! Please visit the <a href="https://talk.observablehq.com">Observable forum</a> or our <a href="https://github.com/observablehq/framework/discussions">GitHub discussions</a>.</p>
 </div>
 
-<div class="caution">Framework does not currently support Windows, though some users have had success with the <a href="https://learn.microsoft.com/en-us/windows/wsl/install">Windows Subsystem for Linux (WSL)</a>. It you are interested in Windows support, please upvote <a href="https://github.com/observablehq/framework/issues/90">#90</a>.</div>
-
 To create a new project with npm, run:
 
 <pre data-copy>npm init @observablehq</pre>
@@ -223,7 +221,7 @@ Or with Yarn:
 
 You should see something like this:
 
-<pre data-copy="none"><b class="green">Observable Framework</b> v1.0.0
+<pre data-copy="none"><b class="green">Observable Framework</b> v1.1.2
 ↳ <u><a href="http://127.0.0.1:3000/" style="color: inherit;">http://127.0.0.1:3000/</a></u></pre>
 
 <div class="tip">

docs/search.md

@@ -31,3 +31,13 @@ index: true
 ```
 
 Search is case-insensitive. The indexing script tries to avoid common pitfalls by ignoring HTML tags and non-word characters such as punctuation. It also ignores long words, as well as sequences that contain more than 6 digits (such as API keys, for example).
+
+You can specify additional comma-separated words to index using the **keywords** option in [Markdown front matter](./markdown). For example:
+
+```yaml
+---
+keywords: file, fileattachment
+---
+```
+
+These keywords are boosted at the same weight as the page title.

docs/telemetry.md

@@ -54,7 +54,7 @@ We never collect identifying or sensitive information, such as environment varia
 Setting the `OBSERVABLE_TELEMETRY_DISABLE` environment variable to `true` disables telemetry collection entirely. For example:
 
 ```sh
-OBSERVABLE_TELEMETRY_DISABLE=true yarn build
+OBSERVABLE_TELEMETRY_DISABLE=true npm run build
 ```
 
 Setting the `OBSERVABLE_TELEMETRY_DEBUG` environment variable to `true` also disables telemetry collection, instead printing telemetry data to stderr. Use this to inspect what telemetry data would be collected.

examples/api/package.json

@@ -3,12 +3,12 @@
   "scripts": {
     "dev": "observable preview",
     "build": "rm -rf dist && observable build",
-    "postinstall": "ln -sf ../../../../bin/observable-init.js node_modules/.bin/observable"
+    "postinstall": "ln -sf ../../../../dist/bin/observable.js node_modules/.bin/observable"
   },
   "dependencies": {
     "@observablehq/framework": "link:../.."
   },
   "engines": {
-    "node": ">=20.6"
+    "node": ">=18"
   }
 }

examples/chess/package.json

@@ -3,7 +3,7 @@
   "scripts": {
     "dev": "observable preview",
     "build": "rm -rf dist && observable build",
-    "postinstall": "ln -sf ../../../../bin/observable-init.js node_modules/.bin/observable"
+    "postinstall": "ln -sf ../../../../dist/bin/observable.js node_modules/.bin/observable"
   },
   "dependencies": {
     "@observablehq/framework": "link:../..",
@@ -12,6 +12,6 @@
     "jszip": "^3.10.1"
   },
   "engines": {
-    "node": ">=20.6"
+    "node": ">=18"
   }
 }

examples/eia/package.json

@@ -3,7 +3,7 @@
   "scripts": {
     "dev": "observable preview",
     "build": "rm -rf dist && observable build",
-    "postinstall": "ln -sf ../../../../bin/observable-init.js node_modules/.bin/observable"
+    "postinstall": "ln -sf ../../../../dist/bin/observable.js node_modules/.bin/observable"
   },
   "dependencies": {
     "@observablehq/framework": "link:../..",
@@ -13,6 +13,6 @@
     "topojson-simplify": "^3.0.3"
   },
   "engines": {
-    "node": ">=20.6"
+    "node": ">=18"
   }
 }

examples/google-analytics/package.json

@@ -3,15 +3,15 @@
   "scripts": {
     "dev": "observable preview",
     "build": "rm -rf dist && observable build",
-    "postinstall": "ln -sf ../../../../bin/observable-init.js node_modules/.bin/observable"
+    "postinstall": "ln -sf ../../../../dist/bin/observable.js node_modules/.bin/observable"
   },
   "dependencies": {
     "@google-analytics/data": "^4.3.0",
     "@observablehq/framework": "link:../..",
     "dotenv": "^16.3.1"
   },
   "engines": {
-    "node": ">=20.6"
+    "node": ">=18"
   },
   "devDependencies": {
     "@types/node": "^20.10.6"

examples/hello-world/package.json

@@ -3,12 +3,12 @@
   "scripts": {
     "dev": "observable preview",
     "build": "rm -rf dist && observable build",
-    "postinstall": "ln -sf ../../../../bin/observable-init.js node_modules/.bin/observable"
+    "postinstall": "ln -sf ../../../../dist/bin/observable.js node_modules/.bin/observable"
   },
   "dependencies": {
     "@observablehq/framework": "link:../.."
   },
   "engines": {
-    "node": ">=20.6"
+    "node": ">=18"
   }
 }

examples/mortgage-rates/package.json

@@ -3,14 +3,14 @@
   "scripts": {
     "dev": "observable preview",
     "build": "rm -rf dist && observable build",
-    "postinstall": "ln -sf ../../../../bin/observable-init.js node_modules/.bin/observable"
+    "postinstall": "ln -sf ../../../../dist/bin/observable.js node_modules/.bin/observable"
   },
   "dependencies": {
     "@observablehq/framework": "link:../..",
     "d3-fetch": "^3.0.1",
     "d3-time-format": "^4.1.0"
   },
   "engines": {
-    "node": ">=20.6"
+    "node": ">=18"
   }
 }

examples/penguin-classification/package.json

@@ -3,12 +3,12 @@
   "scripts": {
     "dev": "observable preview",
     "build": "rm -rf dist && observable build",
-    "postinstall": "ln -sf ../../../../bin/observable-init.js node_modules/.bin/observable"
+    "postinstall": "ln -sf ../../../../dist/bin/observable.js node_modules/.bin/observable"
   },
   "dependencies": {
     "@observablehq/framework": "link:../.."
   },
   "engines": {
-    "node": ">=20.6"
+    "node": ">=18"
   }
 }

examples/plot/package.json

@@ -3,7 +3,7 @@
   "scripts": {
     "dev": "observable preview",
     "build": "rm -rf dist && observable build",
-    "postinstall": "ln -sf ../../../../bin/observable-init.js node_modules/.bin/observable"
+    "postinstall": "ln -sf ../../../../dist/bin/observable.js node_modules/.bin/observable"
   },
   "dependencies": {
     "@observablehq/framework": "link:../..",
@@ -13,7 +13,7 @@
     "dotenv": "^16.3.1"
   },
   "engines": {
-    "node": ">=20.6"
+    "node": ">=18"
   },
   "devDependencies": {
     "@types/node": "^20.10.6"

observablehq.config.ts

@@ -1,6 +1,5 @@
-import {version} from "./package.json" assert {type: "json"};
-
 export default {
+  output: "docs/.observablehq/dist",
   title: "Observable Framework",
   pages: [
     {name: "Getting started", path: "/getting-started"},
@@ -104,7 +103,7 @@ export default {
       <span class="hide-if-small">Observable</span> Framework
     </a>
     <span style="display: flex; align-items: baseline; gap: 0.5rem; font-size: 14px;">
-      <a target="_blank" href="https://github.com/observablehq/framework/releases"><span>${version}</span></a>
+      <a target="_blank" href="https://github.com/observablehq/framework/releases"><span>${process.env.npm_package_version}</span></a>
       <a target="_blank" href="https://github.com/observablehq/framework"><span>GitHub</span></a>
     </span>
   </div>