rameshvarun / blog-cells Goto Github PK

View Code? Open in Web Editor NEW

473.0 6.0 2.0 2.45 MB

Add interactive code snippets to any blog or webpage.

Home Page: https://rameshvarun.github.io/blog-cells/

License: MIT License

HTML 25.52% CSS 7.34% TypeScript 61.37% JavaScript 5.77%

literate-programming typescript blogging javascript notebooks live-coding python

blog-cells's Introduction

blog-cells

[VIEW DEMO]

Add interactive code cells to any webpage, similar to Jupyter or ObservableHQ. Works with direct HTML editing, static site generators like Jekyll / Hugo, and more.

Usage

Quickstart

Just drop in JS / CSS imports and start creating code cells using <script type="text/notebook-cell"> elements. blog-cells will transform these script tags into interactive, runnable code snippets.

<!-- Import blog-cells JS and CSS files. -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/blog-cells.css" />
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/blog-cells.js"></script>

<!-- Create your code cells in script tags -->
<script type="text/notebook-cell">
console.log("Hello World!");
</script>

Try it on CodePen or JSFiddle.

Other Languages

In addition to JavaScript, you can also embed code in other languages by adding a data-kernel attribute.

<script type="text/notebook-cell" data-kernel="python">
print("Hello World!")
</script>

The following kernel values are currently supported:

javascript (Default)
python

Cell Attributes

Cells can be configured with the following attributes:

data-autorun="true" - Automatically run a cell on page load. Autorun cells are run in the order that they appear on the page.
data-hidden="true" - Make a cell hidden by default - readers can toggle the cell's visibility.

Using `<pre>` tags instead of `<script>` tags

Script tags are great for defining notebook cells since they can hold pretty much any code without escaping. However, you can also use <pre class="notebook-cell"> tags instead. When using pre tags, reserved HTML characters should be escaped using HTML entities (this can be done by your static site generator).

<pre class="notebook-cell">
console.log("&lt;b&gt;HELLO&lt;/b&gt;");
</pre>

Creating a Custom Kernel

You can easily define and use your own custom kernels.

<!-- Import blog-cells JS and CSS files. -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/[email protected]/dist/blog-cells.css" />
<script src="https://cdn.jsdelivr.net/npm/[email protected]/dist/blog-cells.js"></script>

<!-- Define custom kernel -->
<script>
class JSONFormatKernel extends BlogCells.Kernel {
  async run(code, onOutput) {
    const data = JSON.parse(code.trim());
    onOutput({ type: "log", line: JSON.stringify(data, undefined, 2) });
  }
}
BlogCells.registerKernel("json-format", () => new JSONFormatKernel());
</script>
  
<!-- Use custom Kernel -->
<script type="text/notebook-cell" data-kernel="json-format">
[4, {"hello": 3}]
</script>

Developing

git clone https://github.com/rameshvarun/blog-cells.git
cd blog-cells
npm install
npm start

Attributions

This repo contains assets from other open source projects.

https://github.com/SamHerbert/SVG-Loaders (MIT)

Alternatives

blog-cells's People

Contributors

Stargazers

Watchers

Forkers

triptych zahidhasanemran

blog-cells's Issues

Support Python

Already implemented here: https://blog.varunramesh.net/posts/simple-python-tips/

Support TypeScript

The first step is to simply support type annotations that are unchecked (should be pretty easy with Babel). The next step (more complex) is to actually typecheck.

It should be possible but may require some parsing + creation of .d.ts files.

Custom Kernels

You should be able to define your own Kernel in a script tag and use it. Something like this:

<!-- Import Blog Cells -->
<script type="module" src="blog-cells.js" />

<!-- Define Kernel -->
<script>
class CustomKernel extends BlogCells.Kernel {
  async run(code, onOutput) {
    ...
  }
}

BlogCells.registerKernel("custom", () => new CustomKernel());
</script>

<!-- Create Cell -->
<script type="text/notebook-cell" data-kernel="custom">
code_in_a_custom_language()
</script>

Support Style Customizations

[Python] Allow top-level await

Allow top level await, mainly for things like installing packages through micropip. Ideally this would happen automatically, but worst-case let the user mark a specific cell as an async cell.

Remove Font Awesome

We don't need to import font-awesome for just a few icons.

Need to document data- attributes

In looking at the demo page I see:

  data-autorun=true
  data-hidden=true

added to the script tag. Are there more?

Support Languages through RISC-V Emulation

Right now, we only support languages where the compiler/interpreter itself can run in WASM. For many languages, this will never be well supported (even if it's possible to hack it together).

We can support a wider variety of languages by emulating a RISC-V, linux-based machine. This should work particularly well for C, C++, and Rust, and allow code to use I/O, threading, and more that wouldn't be possible in pure WASM.

To keep machine images small, we should create minimal linux images using buildroot/busybox.

Example: https://bellard.org/jslinux/vm.html?cpu=riscv64&url=buildroot-riscv64.cfg&mem=256

x86 emulation could also be used (example: https://supabase.com/blog/postgres-wasm), but due to the complexity of the ISA, most x86 emulators only emulate a portion of the spec.

Investigate Web Components / Shadow Dom

Better Error Reporting

Currently there are no stack traces. Possibly use https://github.com/stacktracejs/stacktrace.js/ to parse errors and format them so that they make sense to user.

Get Rid of the `$`

There are three ways to get rid of the $ requirement, but all have trade-offs.

Install exports onto globalThis. This could clobber built-ins and break things For example, if someone writes the code export const postMessage = () => {}, the worker won't be able communicate with the main page anymore.
Auto-destructure values from $, eg add "const a = $.a" to the prelude. However this would make values early bound, whereas we want them to be late bound (lookup on use).
Use Babel to transpile unbound globals, eg "console.log(a) -> console.log($.a)". However, it means that newer JS syntax can't be used in a notebook without upgrading it's Babel version.

Already implemented 3 in 283d100, but removed since I didn't have time to fully test.

Autoscroll Output Logs

When a new output line appears, we should auto-scroll to the bottom.

Can't Load Directly from CDN

It would be great if you could simply import the scripts from a CDN, but by default, this doesn't seem to be possible since workers from remote domains can't be loaded without explicit CSP headers (which many people can't control).

There are maybe some workarounds but if there's a chance browsers could break them in the future, the best thing to do is make it easy for people to download the JS / CSS into their own site's folder.

Handle noscript Better

Right now, with Javascript disabled, the code simply doesn't show at all. We should handle this better. Maybe let people create code cells in <pre> tags and transform them in-place into cells?

Improve UI popping

Is output scope available to the main document?

I would like to run: let name = "Danny"

And then have my code in the main document check what value name is.

Preferable as a property bag or something on the blog-cell itself, as there will be multiple on the page.

Brings me to the second feature request; can the blog-cell emit a Event, so I now calculation was done.