From 15926ab5e49613ce9a2550129fd3d30a67cc991e Mon Sep 17 00:00:00 2001 From: CobusT Date: Mon, 12 Aug 2024 13:30:09 -0700 Subject: [PATCH 01/13] convert documentation --- docs/markdown.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) diff --git a/docs/markdown.md b/docs/markdown.md index e3ee11923..8b53ff582 100644 --- a/docs/markdown.md +++ b/docs/markdown.md @@ -368,3 +368,49 @@ You may also want to add `noopener noreferrer` if linking to an untrusted origin ![A horse](./horse.jpg) ![A happy kitten](https://placekitten.com/200/300) ``` + +## Converting from a notebook + +To create a Markdown file from a public notebook, use the `observable convert` command: + +```sh echo +npm run observable convert +``` +Or with Yarn: +```sh echo +yarn observable convert +``` +Note that, due to [syntax differences](https://observablehq.com/framework/javascript) between Observable notebooks and +Observable Framework, converted notebooks may require further +changes to function correctly. For example, to convert the notebook at `https://observablehq.com/@d3/zoomable-sunburst` to Markdown, run the following command in your `docs` directory: + +```sh echo +npm run observable convert https://observablehq.com/@d3/zoomable-sunburst +``` + +This will create 2 files: `zoomable-sunburst.md` and `flare-2.json` (the file attachment in the notebook). You can then view the markdown file in your dev environment, but you will see a few errors that needs to be corrected: + +Change the `chart` cell definition to an arrow function: +```js run=false +const chart = () => { + // Specify the chart’s dimensions. + const width = 928; + const height = width; + ... +``` + +and the file attachment code to: +~~~js run=false +```js +const data = FileAttachment("flare-2.json").json() +``` +~~~ + +and then, finally, add a JavaScript code block to display the chart: +~~~js run=false +```js +display(chart()); +``` +~~~ + + From df251812aefb59f343ea37973935c140f8cf7c67 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Mon, 12 Aug 2024 17:50:47 -0400 Subject: [PATCH 02/13] edits --- docs/markdown.md | 38 +++++++++++++++++++++----------------- 1 file changed, 21 insertions(+), 17 deletions(-) diff --git a/docs/markdown.md b/docs/markdown.md index 8b53ff582..3065dabe9 100644 --- a/docs/markdown.md +++ b/docs/markdown.md @@ -369,28 +369,30 @@ You may also want to add `noopener noreferrer` if linking to an untrusted origin ![A happy kitten](https://placekitten.com/200/300) ``` -## Converting from a notebook +## Converting notebooks -To create a Markdown file from a public notebook, use the `observable convert` command: +To help you convert a public Observable notebook to Observable Markdown, Framework includes the `observable convert` utility. Just run: ```sh echo npm run observable convert ``` + Or with Yarn: + ```sh echo yarn observable convert ``` -Note that, due to [syntax differences](https://observablehq.com/framework/javascript) between Observable notebooks and -Observable Framework, converted notebooks may require further -changes to function correctly. For example, to convert the notebook at `https://observablehq.com/@d3/zoomable-sunburst` to Markdown, run the following command in your `docs` directory: - + +Note that, due to [syntax differences](./javascript) between notebooks and Framework, the resulting page may require further changes to function correctly. For example, to convert the notebook at `https://observablehq.com/@d3/zoomable-sunburst` to Observable Markdown, run the following command in the project directory: + ```sh echo npm run observable convert https://observablehq.com/@d3/zoomable-sunburst ``` -This will create 2 files: `zoomable-sunburst.md` and `flare-2.json` (the file attachment in the notebook). You can then view the markdown file in your dev environment, but you will see a few errors that needs to be corrected: +This creates two files: `zoomable-sunburst.md` (combining Markdown and JavaScript) and `flare-2.json` (data). Move them to your documents folder (_e.g._, `src/`), then [preview](./getting-started#test-live-preview) the page (typically at `http://127.0.0.1:3000/zoomable-sunburst`). You should see a few errors that need to be corrected: + +a) Change the `chart` cell definition to an arrow function: -Change the `chart` cell definition to an arrow function: ```js run=false const chart = () => { // Specify the chart’s dimensions. @@ -399,18 +401,20 @@ const chart = () => { ... ``` -and the file attachment code to: -~~~js run=false -```js -const data = FileAttachment("flare-2.json").json() +b) Edit the file attachment code block like so: + +````js run=false +```js +const data = FileAttachment("flare-2.json").json(); ``` -~~~ +```` -and then, finally, add a JavaScript code block to display the chart: -~~~js run=false +c) Add a JavaScript code block to display the chart: + +````js run=false ```js display(chart()); ``` -~~~ - +```` +Enjoy! 🚀 From 1c5a3bd82d2d194d4d6abd839a2053ee37db6429 Mon Sep 17 00:00:00 2001 From: CobusT Date: Mon, 12 Aug 2024 22:04:48 -0700 Subject: [PATCH 03/13] moved to a new page --- docs/converting-notebooks.md | 52 ++++++++++++++++++++++++++++++++++++ docs/markdown.md | 49 --------------------------------- observablehq.config.ts | 1 + 3 files changed, 53 insertions(+), 49 deletions(-) create mode 100644 docs/converting-notebooks.md diff --git a/docs/converting-notebooks.md b/docs/converting-notebooks.md new file mode 100644 index 000000000..11efff4d3 --- /dev/null +++ b/docs/converting-notebooks.md @@ -0,0 +1,52 @@ +# Converting notebooks + +To help you convert a public Observable notebook to Observable Markdown, Framework includes the `observable convert` utility. Just run: + +```sh echo +npm run observable convert +``` + +Or with Yarn: + +```sh echo +yarn observable convert +``` + +Note that, due to [syntax differences](./javascript) between notebooks and Framework, the resulting page may require further changes to function correctly. + +## Example + +For example, to convert the notebook at [`https://observablehq.com/@d3/zoomable-sunburst`](https://observablehq.com/@d3/zoomable-sunburst) to Observable Markdown, run the following command in the project directory: + +```sh echo +npm run observable convert https://observablehq.com/@d3/zoomable-sunburst +``` + +This creates two files: `zoomable-sunburst.md` (combining Markdown and JavaScript) and `flare-2.json` (data). Move them to your documents folder (_e.g._, `src/`), then [preview](./getting-started#test-live-preview) the page (typically at [`http://127.0.0.1:3000/zoomable-sunburst`](http://127.0.0.1:3000/zoomable-sunburst)). You should see a few errors that need to be corrected: + +a) Change the `chart` cell definition to an arrow function: + +```js run=false +const chart = () => { + // Specify the chart’s dimensions. + const width = 928; + const height = width; + ... +``` + +b) Edit the file attachment code block like so: + +````js run=false +```js +const data = FileAttachment("flare-2.json").json(); +``` +```` + +c) Add a JavaScript code block to display the chart: + +````js run=false +```js +display(chart()); +``` +```` + diff --git a/docs/markdown.md b/docs/markdown.md index 3065dabe9..8cbbe6ab0 100644 --- a/docs/markdown.md +++ b/docs/markdown.md @@ -369,52 +369,3 @@ You may also want to add `noopener noreferrer` if linking to an untrusted origin ![A happy kitten](https://placekitten.com/200/300) ``` -## Converting notebooks - -To help you convert a public Observable notebook to Observable Markdown, Framework includes the `observable convert` utility. Just run: - -```sh echo -npm run observable convert -``` - -Or with Yarn: - -```sh echo -yarn observable convert -``` - -Note that, due to [syntax differences](./javascript) between notebooks and Framework, the resulting page may require further changes to function correctly. For example, to convert the notebook at `https://observablehq.com/@d3/zoomable-sunburst` to Observable Markdown, run the following command in the project directory: - -```sh echo -npm run observable convert https://observablehq.com/@d3/zoomable-sunburst -``` - -This creates two files: `zoomable-sunburst.md` (combining Markdown and JavaScript) and `flare-2.json` (data). Move them to your documents folder (_e.g._, `src/`), then [preview](./getting-started#test-live-preview) the page (typically at `http://127.0.0.1:3000/zoomable-sunburst`). You should see a few errors that need to be corrected: - -a) Change the `chart` cell definition to an arrow function: - -```js run=false -const chart = () => { - // Specify the chart’s dimensions. - const width = 928; - const height = width; - ... -``` - -b) Edit the file attachment code block like so: - -````js run=false -```js -const data = FileAttachment("flare-2.json").json(); -``` -```` - -c) Add a JavaScript code block to display the chart: - -````js run=false -```js -display(chart()); -``` -```` - -Enjoy! 🚀 diff --git a/observablehq.config.ts b/observablehq.config.ts index ad7a1acff..258d76eff 100644 --- a/observablehq.config.ts +++ b/observablehq.config.ts @@ -30,6 +30,7 @@ export default { {name: "Themes", path: "/themes"}, {name: "Configuration", path: "/config"}, {name: "Deploying", path: "/deploying"}, + {name: "Converting notebooks", path: "/converting-notebooks"}, {name: "Examples", path: "https://github.com/observablehq/framework/tree/main/examples"}, { name: "Inputs", From 907cc43ce15c4991cf8ee9069776e1f27ff7a62d Mon Sep 17 00:00:00 2001 From: CobusT Date: Mon, 12 Aug 2024 22:05:29 -0700 Subject: [PATCH 04/13] removed newline from markdown.md --- docs/markdown.md | 1 - 1 file changed, 1 deletion(-) diff --git a/docs/markdown.md b/docs/markdown.md index 8cbbe6ab0..e3ee11923 100644 --- a/docs/markdown.md +++ b/docs/markdown.md @@ -368,4 +368,3 @@ You may also want to add `noopener noreferrer` if linking to an untrusted origin ![A horse](./horse.jpg) ![A happy kitten](https://placekitten.com/200/300) ``` - From 831c35554ddec0493b5fc416476c1f1824274eef Mon Sep 17 00:00:00 2001 From: CobusT Date: Tue, 13 Aug 2024 16:32:29 -0700 Subject: [PATCH 05/13] added a section of 'things to note' - didn't want to call them limitations --- docs/converting-notebooks.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/docs/converting-notebooks.md b/docs/converting-notebooks.md index 11efff4d3..bd2dd24dc 100644 --- a/docs/converting-notebooks.md +++ b/docs/converting-notebooks.md @@ -50,3 +50,10 @@ display(chart()); ``` ```` +## Things to note + +- The `convert` utility only works with **public notebooks** at this point. We may add support for private notebooks in the future. +- It doesn't support **notebook imports**. If your notebook imports cells from other notebooks, you could manually copy the code from those notebooks into your converted markdown file. +- No support for **Observable JavaScript syntax**. You will need to adjust the code to work with [Framework's JavaScript syntax](/javascript). +- **Reactivity** works slightly differently in Framework. For example, instead of using `viewof` with the Inputs library, you use `view`. See the [Reactivity](/reactivity) section for more details. +- Framework uses a slightly different **Standard Library** than notebooks. You may need to adjust the code to work with Framework's Standard Library. From 5d26eede8c821b40aaf6186d78d84c1f8be7560f Mon Sep 17 00:00:00 2001 From: Mike Bostock Date: Tue, 13 Aug 2024 22:34:48 -0400 Subject: [PATCH 06/13] checkpoint edits --- docs/convert.md | 108 +++++++++++++++++++++++++++++++++++ docs/converting-notebooks.md | 59 ------------------- observablehq.config.ts | 2 +- 3 files changed, 109 insertions(+), 60 deletions(-) create mode 100644 docs/convert.md delete mode 100644 docs/converting-notebooks.md diff --git a/docs/convert.md b/docs/convert.md new file mode 100644 index 000000000..9f00d94eb --- /dev/null +++ b/docs/convert.md @@ -0,0 +1,108 @@ +# Converting notebooks + +Framework’s built-in `convert` command helps you convert an [Observable notebook](https://observablehq.com/documentation/notebooks/) to standard [Markdown](./markdown) for use with Observable Framework. To convert a notebook, you just need its URL; pass it to the `convert` command like so: + +```sh echo +npm run observable convert +``` + +
+ +The `convert` command currently only supports public notebooks. To convert a private notebook, you can (temporarily) make the notebook public unlisted by clicking **Share…** on the notebook and choosing **Can view (unlisted)** under **Public** access. Please upvote [#1578](https://github.com/observablehq/framework/issues/1578) if you are interested in support for converting private notebooks. + +
+ +For example, to convert D3’s [_Zoomable sunburst_](https://observablehq.com/@d3/zoomable-sunburst) example: + +```sh echo +npm run observable convert https://observablehq.com/@d3/zoomable-sunburst +``` + +This will output something like: + + + +
┌   observable convert 
+│
+◇  Downloaded zoomable-sunburst.md in 443ms
+│
+◇  Downloaded flare-2.json in 288ms
+│
+└  1 notebook converted; 2 files written
+ +The `convert` command generates files in the current working directory. The command above generates two files: zoomable-sunburst.md, a Markdown file representing the converted notebook; and flare-2.json, an attached JSON file. + +## Limitations + +Due to differences between Observable Framework and Observable notebooks, the `convert` command typically won’t produce a working Markdown page out of the box. You’ll need to make some further edits to the generated Markdown. + +Differences between Framework and notebooks fall into three categories: + +- JavaScript syntax, including imports +- the standard library +- recommended libraries + +We’ll describe each of these below with examples. + +### Syntax differences + +While Framework uses [vanilla JavaScript](./javascript), Observable notebooks do not; notebooks use [Observable JavaScript](https://observablehq.com/documentation/cells/observable-javascript), which extends JavaScript syntax with a few critical differences. While these differences are often small, you will likely have to edit the converted code to make it conform to vanilla JavaScript syntax and work correctly in Framework. + +TK Example of a `chart` cell declaration. + +a) Change the `chart` cell definition to an arrow function: + +```js run=false +const chart = () => { + // Specify the chart’s dimensions. + const width = 928; + const height = width; + ... +``` + +b) Edit the file attachment code block like so: + +````js run=false +```js +const data = FileAttachment("flare-2.json").json(); +``` +```` + +c) Add a JavaScript code block to display the chart: + +````js run=false +```js +display(chart()); +``` +```` + +- It doesn't support **notebook imports**. If your notebook imports cells from other notebooks, you could manually copy the code from those notebooks into your converted markdown file. + +### Standard library differences + +TK + +### Recommended library differences + +TK + +## Command-line flags + +``` +--output +``` + +``` +--force +``` diff --git a/docs/converting-notebooks.md b/docs/converting-notebooks.md deleted file mode 100644 index bd2dd24dc..000000000 --- a/docs/converting-notebooks.md +++ /dev/null @@ -1,59 +0,0 @@ -# Converting notebooks - -To help you convert a public Observable notebook to Observable Markdown, Framework includes the `observable convert` utility. Just run: - -```sh echo -npm run observable convert -``` - -Or with Yarn: - -```sh echo -yarn observable convert -``` - -Note that, due to [syntax differences](./javascript) between notebooks and Framework, the resulting page may require further changes to function correctly. - -## Example - -For example, to convert the notebook at [`https://observablehq.com/@d3/zoomable-sunburst`](https://observablehq.com/@d3/zoomable-sunburst) to Observable Markdown, run the following command in the project directory: - -```sh echo -npm run observable convert https://observablehq.com/@d3/zoomable-sunburst -``` - -This creates two files: `zoomable-sunburst.md` (combining Markdown and JavaScript) and `flare-2.json` (data). Move them to your documents folder (_e.g._, `src/`), then [preview](./getting-started#test-live-preview) the page (typically at [`http://127.0.0.1:3000/zoomable-sunburst`](http://127.0.0.1:3000/zoomable-sunburst)). You should see a few errors that need to be corrected: - -a) Change the `chart` cell definition to an arrow function: - -```js run=false -const chart = () => { - // Specify the chart’s dimensions. - const width = 928; - const height = width; - ... -``` - -b) Edit the file attachment code block like so: - -````js run=false -```js -const data = FileAttachment("flare-2.json").json(); -``` -```` - -c) Add a JavaScript code block to display the chart: - -````js run=false -```js -display(chart()); -``` -```` - -## Things to note - -- The `convert` utility only works with **public notebooks** at this point. We may add support for private notebooks in the future. -- It doesn't support **notebook imports**. If your notebook imports cells from other notebooks, you could manually copy the code from those notebooks into your converted markdown file. -- No support for **Observable JavaScript syntax**. You will need to adjust the code to work with [Framework's JavaScript syntax](/javascript). -- **Reactivity** works slightly differently in Framework. For example, instead of using `viewof` with the Inputs library, you use `view`. See the [Reactivity](/reactivity) section for more details. -- Framework uses a slightly different **Standard Library** than notebooks. You may need to adjust the code to work with Framework's Standard Library. diff --git a/observablehq.config.ts b/observablehq.config.ts index 258d76eff..8d581c356 100644 --- a/observablehq.config.ts +++ b/observablehq.config.ts @@ -30,7 +30,6 @@ export default { {name: "Themes", path: "/themes"}, {name: "Configuration", path: "/config"}, {name: "Deploying", path: "/deploying"}, - {name: "Converting notebooks", path: "/converting-notebooks"}, {name: "Examples", path: "https://github.com/observablehq/framework/tree/main/examples"}, { name: "Inputs", @@ -83,6 +82,7 @@ export default { {name: "ZIP", path: "/lib/zip"} ] }, + {name: "Converting notebooks", path: "/convert"}, {name: "Contributing", path: "/contributing", pager: false} ], base: "/framework", From cc35274735e65be5db5fba74dcbf136cee5f6aa1 Mon Sep 17 00:00:00 2001 From: Mike Bostock Date: Tue, 13 Aug 2024 22:43:21 -0400 Subject: [PATCH 07/13] multi-convert --- docs/convert.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/docs/convert.md b/docs/convert.md index 9f00d94eb..15570de11 100644 --- a/docs/convert.md +++ b/docs/convert.md @@ -12,6 +12,12 @@ The `convert` command currently only supports public notebooks. To convert a pri +
+ +You can pass multiple URLs to convert many notebooks simultaneously. + +
+ For example, to convert D3’s [_Zoomable sunburst_](https://observablehq.com/@d3/zoomable-sunburst) example: ```sh echo From 97af917979bb3817b8d8d438cd9a6353925bf7d7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Wed, 14 Aug 2024 14:18:45 +0200 Subject: [PATCH 08/13] more docs --- docs/convert.md | 87 ++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 76 insertions(+), 11 deletions(-) diff --git a/docs/convert.md b/docs/convert.md index 15570de11..ed62966e9 100644 --- a/docs/convert.md +++ b/docs/convert.md @@ -18,7 +18,7 @@ You can pass multiple URLs to convert many notebooks simultaneously. -For example, to convert D3’s [_Zoomable sunburst_](https://observablehq.com/@d3/zoomable-sunburst) example: +For example, to convert D3’s [_Zoomable sunburst_](https://observablehq.com/@d3/zoomable-sunburst): ```sh echo npm run observable convert https://observablehq.com/@d3/zoomable-sunburst @@ -65,44 +65,109 @@ We’ll describe each of these below with examples. While Framework uses [vanilla JavaScript](./javascript), Observable notebooks do not; notebooks use [Observable JavaScript](https://observablehq.com/documentation/cells/observable-javascript), which extends JavaScript syntax with a few critical differences. While these differences are often small, you will likely have to edit the converted code to make it conform to vanilla JavaScript syntax and work correctly in Framework. -TK Example of a `chart` cell declaration. +For instance, let’s see how we fix the page converted from the [Zoomable sunburst](https://observablehq.com/@d3/zoomable-sunburst) notebook. At the bottom of the page we see that the `data` cell was transformed into: -a) Change the `chart` cell definition to an arrow function: +````js run=false +```js echo +data = FileAttachment("flare-2.json").json() +``` +```` -```js run=false -const chart = () => { +Fix this with the `const` keyword: + +````js run=false +```js echo +const data = FileAttachment("flare-2.json").json(); +``` +```` + +The largest code block at the top, named `chart`, contains the following: + +````js run=false +```js +chart = { // Specify the chart’s dimensions. const width = 928; const height = width; ... + return svg.node(); +} ``` +```` -b) Edit the file attachment code block like so: +There are various ways to make this into vanilla JavaScript. One possibility is to remove the main curly braces, like so: ````js run=false ```js -const data = FileAttachment("flare-2.json").json(); +// Specify the chart’s dimensions. +const width = 928; +const height = width; +... +const chart = svg.node(); ``` ```` -c) Add a JavaScript code block to display the chart: +Furthermore, we’ll need to [explicitly display](./javascript#explicit-display) the `chart` variable: ````js run=false ```js -display(chart()); +// Specify the chart’s dimensions. +const width = 928; +const height = width; +... +const chart = display(svg.node()); ``` ```` -- It doesn't support **notebook imports**. If your notebook imports cells from other notebooks, you could manually copy the code from those notebooks into your converted markdown file. +(An alternative transformation would be to create a function called `chart`, and invoke `chart()` as an inline expression where we want to display the output.) + +Observable Markdown doesn’t support **notebook imports**. If your notebook imports cells from other notebooks, you could manually copy the code from those notebooks into your converted markdown file. If you import functions and other helpers, it could be useful to add them to a [local module](./imports#local-imports). ### Standard library differences -TK +The `md` template literal is not available in Observable Markdown; instead, write Markdown directly (or import the `markdown-it` library from npm for advanced usage). + +The `require` and `resolve` functions are not available in Observable Markdown; instead, use `import` and `import.meta.resolve`. + +The `DOM.*`, `Files.*`, `Generators.*` and `Promises.*` methods are not available in Observable Markdown. Instead, use the appropriate vanilla JavaScript code — which you can grab from [observablehq/stdlib](https://github.com/observablehq/stdlib/). For example, to create an image with a [2D context](https://developer.mozilla.org/en-US/docs/Web/API/CanvasRenderingContext2D), you can copy the code from [context2d.js](https://github.com/observablehq/stdlib/blob/main/src/dom/context2d.js): + +```js run=false +function context2d(width, height, dpi) { + if (dpi == null) dpi = devicePixelRatio; + var canvas = document.createElement("canvas"); + canvas.width = width * dpi; + canvas.height = height * dpi; + canvas.style.width = width + "px"; + var context = canvas.getContext("2d"); + context.scale(dpi, dpi); + return context; +} +``` + +Or, to create a Promise that resolves to a given `value` after a given [delay](https://github.com/observablehq/stdlib/blob/main/src/promises/delay.js): + +```js run=false +function delay(duration, value) { + return new Promise(function(resolve) { + setTimeout(function() { + resolve(value); + }, duration); + }); +} +``` + +If you use a specific function often, you can save it to a local module. ### Recommended library differences TK +### Other differences + +Some cell types cannot be converted to Observable Markdown. Data table cells can be replaced by `Inputs.table` (see [issue #23](https://github.com/observablehq/framework/issues/23) for future enhancements), and chart cells can be replaced by Observable Plot’s [auto mark](https://observablehq.com/plot/marks/auto). + +Database connectors can be replaced by [data loaders](./loaders). We recommend using the `.env` file to store your secrets (such as database passwords and API keys) in a central place outside of your checked-in code; see [Google Analytics](https://observablehq.observablehq.cloud/framework-example-google-analytics/) for an example. + ## Command-line flags ``` From cc150e7fc08420ef0a4bb968cafc26abae34d276 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Wed, 14 Aug 2024 14:34:26 +0200 Subject: [PATCH 09/13] recommended libs and command-line flags --- docs/convert.md | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/docs/convert.md b/docs/convert.md index ed62966e9..33efccda5 100644 --- a/docs/convert.md +++ b/docs/convert.md @@ -160,7 +160,7 @@ If you use a specific function often, you can save it to a local module. ### Recommended library differences -TK +In Observable Framework, the recommended [libraries](./imports#implicit-imports) are generally not pinned to a given version — instead you get the latest version that was published on npm (you can still request any version explicitly by using an explicit `import … from "npm:module@version"` statement). Some of them, such as [graphviz](./lib/dot), have been slightly adapted in support of dark mode. For details, see the documentation for each library. ### Other differences @@ -170,10 +170,7 @@ Database connectors can be replaced by [data loaders](./loaders). We recommend u ## Command-line flags -``` ---output -``` +The `convert` command supports the following command-line flags: -``` ---force -``` +- `--output` - the path to the output directory; defaults to `.` for the current working directory. +- `--force` - if true, always download and overwrite existing resources; by default, the script will ask for user input when a file already exists in the output directory. From efbbc5a2b9e3a89e0687ac043b49d3e0ab34dec1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Wed, 14 Aug 2024 16:10:16 +0200 Subject: [PATCH 10/13] fix convert output to default to the source root; add documentation closes #838 --- docs/convert.md | 4 ++-- src/bin/observable.ts | 21 ++++++++++++++++++--- 2 files changed, 20 insertions(+), 5 deletions(-) diff --git a/docs/convert.md b/docs/convert.md index 33efccda5..87634354c 100644 --- a/docs/convert.md +++ b/docs/convert.md @@ -170,7 +170,7 @@ Database connectors can be replaced by [data loaders](./loaders). We recommend u ## Command-line flags -The `convert` command supports the following command-line flags: +Besides `--config` and `--root`, the `convert` command supports the following additional command-line flags: -- `--output` - the path to the output directory; defaults to `.` for the current working directory. +- `--output` - the path to the output directory; defaults to the [source root](./config#root). - `--force` - if true, always download and overwrite existing resources; by default, the script will ask for user input when a file already exists in the output directory. diff --git a/src/bin/observable.ts b/src/bin/observable.ts index 5fbf41d07..0bebbd5db 100755 --- a/src/bin/observable.ts +++ b/src/bin/observable.ts @@ -1,4 +1,5 @@ #!/usr/bin/env node +import {join} from "node:path"; import type {ParseArgsConfig} from "node:util"; import {parseArgs} from "node:util"; import * as clack from "@clack/prompts"; @@ -199,12 +200,26 @@ try { case "convert": { const { positionals, - values: {output, force} + values: {config, root, output: out, force} } = helpArgs(command, { - options: {output: {type: "string", default: "."}, force: {type: "boolean", short: "f"}}, + options: { + output: { + type: "string", + description: "Output directory (defaults to the source root)" + }, + force: { + type: "boolean", + short: "f", + description: "If true, overwrite existing resources" + }, + ...CONFIG_OPTION + }, allowPositionals: true }); - await import("../convert.js").then((convert) => convert.convert(positionals, {output: output!, force})); + // The --output command-line option is relative to the cwd, but the root + // config option (typically "src") is relative to the project root. + const output = out ?? join(root ?? ".", (await readConfig(config, root)).root); + await import("../convert.js").then((convert) => convert.convert(positionals, {output, force})); break; } default: { From 4fc687f5561bec8d677cee9f47ae1c97354d8d7e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Philippe=20Rivi=C3=A8re?= Date: Wed, 14 Aug 2024 17:17:28 +0200 Subject: [PATCH 11/13] Update src/bin/observable.ts Co-authored-by: Mike Bostock --- src/bin/observable.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/bin/observable.ts b/src/bin/observable.ts index 0bebbd5db..81a7e3b39 100755 --- a/src/bin/observable.ts +++ b/src/bin/observable.ts @@ -1,5 +1,5 @@ #!/usr/bin/env node -import {join} from "node:path"; +import {join} from "node:path/posix"; import type {ParseArgsConfig} from "node:util"; import {parseArgs} from "node:util"; import * as clack from "@clack/prompts"; From f682699ba23df5b8c19958b4fc33f6f1050b09ee Mon Sep 17 00:00:00 2001 From: Mike Bostock Date: Thu, 22 Aug 2024 07:36:07 -0600 Subject: [PATCH 12/13] add -o shorthand --- src/bin/observable.ts | 1 + 1 file changed, 1 insertion(+) diff --git a/src/bin/observable.ts b/src/bin/observable.ts index 81a7e3b39..bfcffbe14 100755 --- a/src/bin/observable.ts +++ b/src/bin/observable.ts @@ -205,6 +205,7 @@ try { options: { output: { type: "string", + short: "o", description: "Output directory (defaults to the source root)" }, force: { From a58e2ac6be7370ea1d86bec865ba29e2dcedb0f0 Mon Sep 17 00:00:00 2001 From: Mike Bostock Date: Thu, 22 Aug 2024 07:39:31 -0600 Subject: [PATCH 13/13] update docs --- docs/convert.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/convert.md b/docs/convert.md index 180d7d4c6..6289bf260 100644 --- a/docs/convert.md +++ b/docs/convert.md @@ -55,7 +55,7 @@ This will output something like: │ └ 1 notebook converted; 2 files written -The `convert` command generates files in the current working directory. The command above generates two files: zoomable-sunburst.md, a Markdown file representing the converted notebook; and flare-2.json, an attached JSON file. You can change the output directory using the --output command-line flag. +The `convert` command generates files in the source root of the current project by default (typically `src`); you can change the output directory using the `--output` command-line flag. The command above generates two files: `zoomable-sunburst.md`, a Markdown file representing the converted notebook; and `flare-2.json`, an attached JSON file. Due to differences between Observable Framework and Observable notebooks, the `convert` command typically won’t produce a working Markdown page out of the box; you’ll often need to make further edits to the generated Markdown. We describe these differences below, along with examples of manual conversion.