@mcmcclur I get confused by npm, so I’m not the best guide to why it goes awry, but I can at least try to help you get it to work! I was getting the same error, but yarn global upgrade @observablehq/framework
worked for me. (I installed it with yarn, not npm.) Try which observable
(to see where the version that runs is coming from), or npm list -g
or yarn global list
(to see what versions of @observablehq/create
and @observablehq/framework
you may have installed globally). You might also have a version of the old pre-release @observablehq/cli
lying around, which could be confusing things.
In general, I find it easier to manage packages per-project. To create a new project, I run npm init @observablehq
instead of the global observable create
. If I want to ensure I’m creating a project with the latest version of Framework, I clear the cache with rm -rf ~/.npm/_npx
and then run npm init @observablehq
.
Inside a project, to use the local version of the observable command, you can run npm run observable convert @d3/bar-chart
. (But that always seems to write the md to the project root for me, even if my working directory is /docs.)
I would think that you would run the observable convert
command to create a new project based on a notebook.
A notebook is more analogous to one Markdown page within a project, not a whole project itself, so convert
outputs a .md file. A project is more like a folder of notebooks, so creating a new project should be much more rare than creating a new notebook.
For that matter, a Framework page may not even be that analogous to a notebook. To riff a little on the “cultural” differences between notebooks and Framework projects: as we’ve acclimated to the strengths of each medium, we’ve come to think of notebooks as more like ephemeral open-ended scratchpads, and pages as more stable productionized artifacts. That means different things for different people and different notebooks, but, when we convert an internal notebook analyzing some business metrics to a page in our BI project, we don’t just adjust the syntax. We rewrite dynamic queries as more static data loaders optimized for the most important cases. We rethink the layout to be more of a dense 2D dashboard and less of a literary report. And we may condense several different notebooks exploring different aspects into a single project page, which takes up more “space” because it has to live in the same global project navigation.
To me this learning experience is a lot like learning Plot after D3. At first I try to recreate my favorite D3 things in Plot, and struggle with how that seems to go against the grain; then, gradually, I learn Plot’s strengths, and start making things I would never have tried with D3. And I also grow more comfortable with just sticking with D3 for the things it works better for!