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

Author: Fil

.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

bin/observable-init.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"
+});

build.js

@@ -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/config.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/contributing.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">