Jupytext in Starboard Notebook

Hi Jupytext developers,

I’m building Starboard and its notebook runtime Starboard Notebook. The main difference versus Jupyter is that Starboard runs entirely in the browser: there is no backend server. Python support is possible through Pyodide, see the Python example notebook.

Its current format is based on Project Iodide’s percent format, which is very similar to Jupytext’s percent format (here’s a short discussion on compatability (@westurner for visibility)).

The format currently looks like this:

%% py runOnLoad
import matplotlib.pyplot as plt
plt.plot([i**3 for i in range(20)])
plt.show()

%% py
import pandas as pd
df = pd.DataFrame([1,3,5,7])
df

%% js
console.log("hi");

%% html runOnLoad collapsed
<p>Hello!</p>

I’m looking to transition to a more Jupytext/percent-like representation for (near) compatibility. Especially with Project Iodide no longer being actively developed or maintained this makes more sense.

I think being able to open most ipynb/jupytext files entirely in the browser will be very powerful. Of course the mapping will never be entirely 1-1, so I hope we can discuss what makes sense and you can answer some questions. Here are a few initial questions I hope you can answer:

1. The cell delimiters are currently not “commented” at all. What comment delimiter makes sense? #? //? Starboard notebooks are truly multilingual: you can mix Javascript and Python and have interop between the two so there is no one “kernel” or “script language”. I was personally thinking of just picking #. How would you deal with a corner case like this?

# %% [javascript]
const myString = `
# %% Hello!
`;

1. What is the default cell type? Is it inferred from the file extension? If I were to convert from jupytext script to my format should I put this default type in the metadata, or simply make every cell have an explicit type?

2. Cells have optional titles, could you maybe give an example of when that is used? Can I safely ignore it?

3. A cell’s properties (or not sure what you call them, metadata?) are in key="value" format, how would more complicated values be formatted? Are they always to be interpreted as strings, or does it follow YAML rules? Currently I have only binary flags, how would they be represented?

4. The metadata in Jupytext is currently a block of YAML at the top, with everything under a jupyter.jupytext key, should I keep the same metadata under the same key for compatibility, or do you foresee Jupytext looking for a starboard.jupytext key?

5. A bit unrelated and more food for thought: Have you considered allowing the cell type and metadata to be split over multiple lines, something like this? I was considering supporting it before as the line can become quite long and no longer play nice with version control.

# %% [javascript]
# %% myValue="Hello!"
# %% someOtherValue="bla"
console.log("Hello!");

Or even full YAML support?

# %%* [javascript]
my_metadata:
  v: [1,2,3]
# *%%
console.log("Hello!");

---

Of course I’m also happy to hear any other tips and thoughts!

My current parser is only 40 lines (but gets the job done), I’m not sure how much it will have to grow now.

Thank you in advance 😃

[gzuidhof]

Thank you for the references!

Definitely helpful, especially to see how they handled LaTeX support using KaTeX instead of MathJax, which I now added to Starboard. I can probably take one of their parsers as a starting point for allowing for .ipynb imports 😃

[mwouts]

Great, thanks for sharing!