asg017 / atom-observable Goto Github PK

View Code? Open in Web Editor NEW

11.0 4.0 1.0 7.25 MB

Render Observable notebooks in Atom!

Home Page: https://atom.io/packages/atom-observable

License: MIT License

JavaScript 99.69% CSS 0.07% HTML 0.23%

atom observable-notebook javascript observablehq atom-package

atom-observable's Introduction

atom-observable package

Render full Observable notebooks in Atom!

Installing

Package here. You can apm install atom-observable or just look up atom-observable in the Atom package installer.

Usage

When you have a "notebook" file open, just press Alt+Ctrl+O (or Packages -> atom-observable -> Toggle), and a preview will popup, with the rendered notebook.

Once the preview is open, whenever you save the file, the entire preview will reload. It's not as cool of a dev experience as observablehq.com is, but it's something!

All stdlib should work - DOM, require, html, md, all that. import cells will resolve from observablehq.com by default.

What is a "notebook"?

It's basically just a regular notebook you would write on observablehq.com, but in a file. It can be made of several top-level cell definitions - with import support!

For example:

a = 1

b = 2

c = a + b

viewof name = DOM.input()

md`Hello ${name}!`

import {chart} from "@d3/bar-chart"

Keep in mind - not all javascript files are valid Observable syntax. example_notebooks has a few examples of what could work.

How it works

Most of the magic happens with @alex.garcia/unofficial-observablehq-compiler - an unofficial compiler for Observable notebook syntax. All this package does is basically send the file contents to an iframe, and a script in the iframe uses the compiler to compile it to an element.

Contributing

Please do! There's a ton of potential here - access to node.js, custom libraries, better local development. Take a look at these issues to find something to work on. Just please follow the Contributor Covenant in all your interactions 😄

Acknowledgement

This was built with libraries like @observablehq/runtime and @observablehq/parser which are licensed under ISC.

atom-observable's People

Contributors

Stargazers

Watchers

Forkers

erickwang

atom-observable's Issues

Fix styling of rendered notebook

I haven't investigated this much, but there seems to be some default styling from Atom that also affects the injected iframe. For example, the markdown just looks a little off - wrong font, sizing, max-width compared to observablehq.com. We do have inspector css in the iframe, but maybe there's more CSS we have to add, or some atom-specific styling we have to turn on/off?

Better shortcut? (is Mac supported?)

I just defaulted to Ctrl+Alt+O (since ao == atom observable), but I'm sure something else may make more sense. Does it work with Cmd on macs? I haven't tested that yet

Make syntax highlighter for Observable syntax

Adding syntax highlighting for Observable syntax would be really helpful - for the extra keywords (viewof, mutable), cell/block syntax, etc

I'm not too familiar with how this works, though :/

Import local notebooks

Right now, this just uses the defaultResolver of the unofficial compiler, meaning it imports from observablehq.com notebook directly.

But, it would be cool to support local notebooks that are in your file system. For example, you could have:

$ ls
main.notebook.js other.notebook.js

Then, in main.notebook.js:

import {test} from "./other.notebook.js"

test should now have the test variable from the local other.notebook.js.

This would involve creating a new resolve function and passing it into the Compile constructor. The defaultResolver is a good example to work off of.

Maybe it should be a setting too - since maybe this is a security concern?

Tables not rendered with nice style

It would be great to render tables with the same style!

Add new builtin variables

Since this is running on atom, we could set up a background server that can provide data/API's to the observable runtime to enhance these notebooks.

For example, imagine a env builtin variable that looks up environmental variables, like:

token = env`API_TOKEN`

data = fetch(`https://some.server.com/data?token=${token}`)

Or maybe, a way to directly access files from the filesystem - like:

data = d3.csvParse(await fs(`/home/user/projects/weather/data.csv`))

Or maybe, re-write require to require js modules from the local filesystem (like a node_modules directory)

I'd love to hear suggestions for what are some other cool default variables that could exist!