observable-press // a publishing pattern for notebooks

Hey all, I’ve recently created a little library called observable-press that provides some simple infrastructure and an opinionated pattern for publishing Observable notebooks on other sites. The basic idea is to do all your coding in your notebook, write an HTML skeleton for the content to live in, and let observable-press glue them together. If this doesn’t immediately make sense, the examples in the repo might clarify; here’s a simple demo.

I also used the library to power a simple website [edit: site removed for licensing issues], which takes a notebook and attempts to render a single cell as large as possible.

I originally made this to power a side project that didn’t really go anywhere, but I was surprised how fun it was to build a tiny web app with this technique. I’d love to hear any feedback anyone has.

Sidenote: I do not intend to overstep in any way with the naming of these things, I just wasn’t sure what to call them. If anyone working at Observable objects to these names being too close, I’d be happy to change them, and also happy to hand over the .press domain if you want it for some other purpose – it was $2 so I figured why not.

2 Likes

This looks really interesting, but I’m having trouble loading your examples. In Firefox, I’m getting this error:

SyntaxError: unexpected token: identifier [Learn More] shimport:1:119 (https://unpkg.com/shimport)

​In Chrome, I’m getting:

Uncaught (in promise) SyntaxError: Unexpected token export

and the error points to the export notebook; line in the JS file served by https://api.observablehq.com/

Are you possibly missing a type="module" somewhere in a script tag?

I see the same issue now.

I’m not positive that this is what changed, but I notice that the Observable API response ends with export notebook where I believe it used to end with export default notebook. I don’t believe that export notebook is legal syntax for an export statement; I think it’s supposed to be export {notebook} if the intention is to have notebook as a named export.

When I change it to a default export by hand, it works the way it did earlier – unfortunately I don’t think I can fix this on my end.

Here’s a gist showing what the API currently returns for this notebook, and here’s a modified version that works as expected.

Now, if this isn’t the actual problem, I’ll feel even stupider.

1 Like

Apologies. There was a temporary glitch serving the v=1 module format.

Although we haven’t formally announced it yet, we highly recommend using the newer v=3 module format.

Here’s an example:

https://api.observablehq.com/@mbostock/d3-bar-chart-remix.js?v=3

Ah, you’re right. But it looks like it was changed back, so your pages work in Chrome for me now. They’re still broken in Firefox though. It’s still complaining about shimport; in particular it’s pointing to the 4th line here:

var __shimport__ = function (n) {
  'use strict';
  function t(n, t) {
    for (var r = n.length; r--; ) if (n[r].name === t) return n[r].as /* SyntaxError: unexpected token: identifier */
  }

Cool project. Thank you for sharing. Not that I am one who is (yet) able to help with this sort of thing, a couple of reflections for your consideration:

Your example site on my connection and browser (Chrome) appears slow to the point of being unusable. Not sure if you or others have the same issue.

Your build examples might benefit from starting from (or providing / linking to) the more basic elements you reference (e.g. the ‘html skeleton’). Also helpful might be to summarize all your in-text comments in the code up-front in your README. I really appreciate the length to which you went already to explain things and add disclaimers; i realize this stuff takes time).

It also might help to add more direct links to original observable notebooks alongside your examples in the GitHub documentation. I realize one can grab it from within the example page, but for those finding and exploring your GitHub repo, more surface-level / immediately accessible points of reference for original and finished product could be handy.

Something of a meta-level reflection during my time on Observable:

I continue to struggle with the process of transcribing notebooks from Observable into more basic HTML pages, which I undertake especially to ensure that the page serves out content for older browsers. I still work in a world where people use IE (and it’s still the default on my machine after my employer moved us to Windows 11!), so it’s on me to ensure that this ‘other half’ (those not using another browser) can see my visualizations (or at least get the idea). What I would really appreciate is a tool to help do this, to the greatest extent possible. I think transition between D3.v4 and D3.v5 may have broken the IE compatibility (haven’t verified this, but identified some bugs). And IE doesn’t support the Observable runtime – which leaves me manually re-writing code back into ‘vanilla JS’.

Thanks again to everyone for offering the community these incredible tools and for sharing your ideas, insights, and expertise!

1 Like

Thanks all for your feedback! The updated README and new, simpler examples should help to clarify things.

I unintentionally ran afoul of some licensing issues, so have removed any examples which reference notebooks I didn’t author myself, which is why the only example that was live earlier was a bit confusing (and yes, that animated images notebook is just slow, it’s not you).

@bgchen I think I’ve fixed the cross-browser issues; I thought I had the shimport-based solution working before but it doesn’t want to play nicely with the modules so I blew it all away in favor of a simpler but somewhat hacky solution (see bootstrap.js). I’ve checked that it now works in FF, Chrome, and Safari at least.

2 Likes