Hello, Racketeers. I have a little side project to design a new language, and I thought it would be nice to have docs that let the reader try out the language in a built-in sandbox along the way. It would be a lot like A Tour of Go.
I'd like to use Scribble for the docs. Has anyone explored the idea of embedding a sandbox/REPL into a Scribble page before?
My initial thought is to start from the sandbox code from pasterack.org and the Scribble-based-rendering code from a site like https://lexi-lambda.github.io/. But maybe there are better starting points out there. I'm a Scribble novice, so I definitely don't know what layer of the stack would be right to do this at.
FWIW, I'm not worried about security, production hardening, etc. Just getting something up and running so I can tinker with it. The plan is to evaluate user programs server-side for now, but maybe someday I'll do client-side by compiling to WASM or something.
1 Like
I haven't done this, but the approach you describe sounds very reasonable.
It sounds like you realize this, but one design point is that you need a server to run your sandboxes, whereas Scribble typically used generate static HTML files that work with any generic HTTP server, or even from file:// URLs with no server at all (which restricts a few JavaScript APIs). But this is not a big hurdle.
On the Scribble side, you would probably implement a function like @sandbox{} that would return a “block” value with a customized “style”. This is not a very commonly used part of Scribble, but the manual § 6.11.1 “Implementing Styles” has some examples. (To a lesser extent, the rest of § 6.11 “Extending and Configuring Scribble Output” may also be useful.)
Concretely, you probably want the style properties alt-tag to control the name of the generated HTML element, attributes to add arbitrary attributes to the element, and js-addition to specify a JavaScript resource to be loaded on any page that uses the given element. I think HTML’s custom elements API might be a good fit for what you’re trying to do, but in principle you could just generate iframes.