Suggestion for Notebook Kit Documents: Simple(st) demo setup

[shadoof]

I have been beginning to use Observable Desktop and Notebook Kit to introduce STEM-shy, code-shy humanities and arts students to Observable Notebooks as — this is how I see it — 'pen and paper' for the web, with literate programming (i.e. with original writing, comment(ary) and code fully integrated).

But even a simple 'install' and configuration can be a challenge for the students I am working with. What I hope to have:

1. Writing and coding in notebooks √ Observable Notebook Kit
2. Local development and git versioning √ ditto plus git and other editors
3. Easy deployment to the web without having to possess or set up a server - almost there

(3) Could be addressed by a different default directory structure for local Observable Notebooks:

project-folder/
├── nbks/
│   ├── index.html
│   └── another-notebook.html
├── docs/
│   └──[build files]
└── package.json

With default package.json similar to this:

{
  "dependencies": {
    "@observablehq/notebook-kit": "^2.1.3"
  },
  "scripts": {
    "preview": "notebooks preview --root nbks",
    "build": "notebooks build --root nbks --out ../docs -- nbks/*.html"
  },
  *"devDependencies": {
    "esbuild": "^0.28.0"
  }
}

[*This is an issue.]

Why? Because if the project tracks a free public repo hosted on GitHub, the setup up for GitHub Pages becomes trivially easy. My code-shy students get an easy versioned workflow to a website that they can program themselves, literately.

[mbostock]

Thanks for the continued feedback. We love that you are using Notebooks to teach!

The most direct way we are making it easier to get started with Notebooks is by bringing the Notebooks 2.0 editor to the web. This should be available very soon. Does that help? Then your students won’t need to install anything to get started, but they can transition to local development if and when they want it.

As for your suggested configuration, that seems fine if it works for you? You can create a repository with your desired setup and have people fork it. Or are there features missing from Notebook Kit that you need to achieve your desired configuration?

[shadoof]

Thanks! I am very much looking forward to Notebooks 2.0 for the web and an enhanced return to the no-install environment that I still love using under 1.0. It will be a great help.

My suggested configuration just relates to documentation, once the downloading to local development begins. On behalf of students, whom I will still encourage to build local projects from initially web-based notebooks – thus slotting them into versioning that they can manage themselves – I'm just suggesting that the documentation allows a more or less frictionless-for-newbies setup.

[mbostock]

Thanks for the clarification. If your goal is to make the GitHub Pages setup easier, I would not recommend using the docs folder to commit generated files to git. I would instead use GitHub Actions to do the deployment; you can see our deploy.yml as an example. See also GitHub’s guide, and our earlier guide on Deploying Framework. You could provide a similar deploy.yml to your students.

[shadoof]

Thanks again! Of course you're right.* But I will probably still go the route of guiding students to get a site up and running first with a docs folder. And then, to take them through what's needed to use GitHub Actions which, for some of them, would definitely become both a big and a good learning experience. (If, like me, you're not very good at unix yourself, can you imagine explaining to someone who has never used, or wanted to use, the CLI how to create a directory inside an invisible directory, and then edit a plain text file into it, and do this ... on their Mac. ;)

*And I have, thanks again, snagged and successfully adapted your deploy.yml on one of my working-things-out repos. This whole thing was, in part, triggered by hassles I had trying to repair/update a version-broken deployment yml file.