[ANN] x-ocaml, notebooks as a webcomponent

Ecosystem
1

Dear internets,

I would like to share x-ocaml, a little project to make it easier to share executable OCaml examples on the web. To enable readers to experiment with the code, x-ocaml integrates the CodeMirror editor with the js_of_ocaml-toplevel interpreter, Merlin and OCamlformat. You only need to add the following in your html page to use it:

<script async
  src="https://cdn.jsdelivr.net/gh/art-w/x-ocaml.js@6/x-ocaml.js"
  src-worker="https://cdn.jsdelivr.net/gh/art-w/x-ocaml.js@6/x-ocaml.worker+effects.js"
></script>

This script will introduce a new HTML tag <x-ocaml> to present your OCaml code:

<x-ocaml>let it = "be"</x-ocaml>

The online demo shows a couple more examples and configuration options. In particular, there is a command-line tool in the github repo to export OCaml libraries and load them into your page:

$ x-ocaml --effects digestif.ocaml -o digestif.js
# then use <script async src="..." src-worker="..." src-load="digestif.js">

I believe this could be very useful in tutorials or documentation to showcase your favorite OCaml libraries.

While searching how to implement this, I discovered sketch.sh which had so many good ideas and that we should use a lot more! My hope is that x-ocaml can provide a similar notebook experience for the rest of the web, by being easy to integrate in static webpages.

Besides the js_of_ocaml authors and the many OCaml playgrounds that have inspired this project, I would like to address some special thanks to:

35 Likes
2

Thanks a lot for this great tool!

I instantly ported my old blog post using blogaml to a version with x-ocaml.

The transition was so easy, and the result is so good! Kudos! Love it :slight_smile:

I noticed however a small issue: The doctrings are duplicated, in various position (before or after the compiler’s output, see this block). Maybe this is due to ocamlformat? and btw, is there a way to disable the autoformatting in xocaml?

(We have oxcaml, xocaml, I can smell xoxcaml coming, but I can’t wait for xoxocaml)

XOXO

8 Likes
3

Thanks for trying it out, I’m glad you found it easy to use :slight_smile: (btw one feature I would like to steal from your blogaml notebooks is the button to restore the original code example, that’s a really nice touch!)

Also thanks for reporting the OCamlformat duplicate docstring issue! It should be fixed now, in the @6 release:

<script async
                                                     <!-- vv -->
         src="https://cdn.jsdelivr.net/gh/art-w/x-ocaml.js@6/x-ocaml.js"
  src-worker="https://cdn.jsdelivr.net/gh/art-w/x-ocaml.js@6/x-ocaml.worker+effects.js"
                                     <!-- version changed ^^ -->
></script>

There’s a new x-ocamlformat="..." attribute that you can add to the <script> to pass an OCamlformat configuration, e.g. x-ocamlformat="margin=60". You can turn off the autoformatting with x-ocamlformat="disable".

(It’s useless so I never documented the secret attribute elt-name="xoxo-caml" to rename the <x-ocaml> WebComponent to <xoxo-caml>, but it’s there if you really want it :joy: … note that the custom element name must contain a dash)

6 Likes
4

Yes, please steal it :slight_smile:

Amazing! Thanks for the very very quick fix. Note that in addition to the margin, setting doc-comments=before might be a good idea to avoid having the compiler output inbetween the declaration and the docstring. (And you can use newlines in HTML attribute!)

This is really great. I’m going to use it often (thanks to @patricoferris for pointing out that (after some fixes in slipshow) it can work very well in a presentation setting!)

2 Likes
5

I just checked your blog, but unfortunately the new version does not work for me: when I click Run, something quickly moves around and disappears, and the code comes back in its place. I can Execute the code in your old blog.

1 Like
6

Yes! Take a look here: https://patrick.sirref.org/slipshow-x-xocaml (in particular at the example slipshow), still early days with some CSS to work out etc. but this is really fun. Thank you @art-w and @panglesd for both of these great tools!

2 Likes
7

@patricoferris and @panglesd: Oh I love this, what a fun combination!

@amaro: I’m sorry to hear this! I could not reproduce on my system, so I created an issue to keep track of your report. Do you mind sharing your OS and browser to help me track down the bug? :slight_smile: (either in the github issue or here if it’s more convenient)

8

You really should at a minimum add SRI to these script snippets (if not encourage folks to host first-party for security/privacy—like the blog entry showed). I know it’s meant to look easy to use, but it’s not a good idea be forwarding along information to these CDNs as a default example.