Interactively running code blocks

[3goats]

Hi, I'm experimenting with building out some documentation using Starlight. The docs will contain lots of code blocks. I would like to bind a button to each block which would grab the content of the block and submit it to a server side function/api for processing. I would then like to render the response below the code block. Basically interactive docs. Is there an obvious way to do this using astro/starlight ? Has anybody done something like this previously ?

[Fryuni]

Not with a button to render when the user want it, but since codeblocks are not editable anyway there is astro-live-code by @mattjennings that does exactly that.

Each codeblock that you mark with live will get rendered just below itself. It can even have client interactivity.

[3goats]

Thanks for this. Not sure if this will help me. I need to take the code block and submit it to an API/Endpoint for processing then render the response. Seems that this actually tries to run the code in situ.

[delucis]

Could you share a bit more about what the contents of the code block looks like?

Starlight uses Expressive Code by default for code blocks and these include a copy button that might help your binding: each copy button includes a data-code attribute that contains the raw code input for that code block.

So you could have a custom component that you wrap around the code block, something like this:

<InteractiveBlock>

```js
console.log('example')
```

</InteractiveBlock>

And the InteractiveBlock component might look something like this:

---
// InteractiveBlock.astro
---

<interactive-block>
  <slot />
  
  <button data-run-code>Run code</button>

  <div data-output />
</interactive-block>

<script>
customElements.define('interactive-block', class Block extends HTMLElement {
  connectedCallback() {
    const code = this.querySelector('[data-code]')?.dataset.code;
    const button = this.querySelector('button[data-run-code]');
    if (!code || !button) return;
    button.addEventListener('click', () => {
      // fetch your server response on click and use the `code` variable.
      // for example, you could update the empty <div> from the template above.
    });
  }
});
</script>

[3goats]

Thanks for this, it looks promising.

Here's some more background that hopefully covers what I'm trying to do.

I'm looking for a way to use runme as backend/endpoint to some docs I'm writing. Runme can use web sockets or it provides a JavaScript wrapper that can be used to execute the code passed to it. Runme currently has a vscode extension that can do this, however I want to use starlight to write the docs and make the code interactive. Runme already supports multiple languages, however my example will primarily be Linux shell commands.

Here's an example using MKDocs Material https://venafi.github.io/firefly-playground/os-quick-start/. My goal is to move these docs to Astro/Starlight and have a "run" button alongside the copy buttons. When clicked the code block would be sent to an API/Endpoint for processing with the result rendered below the code block.

[delucis]

Here’s a dummy version of the above that uses eval() to evaluate a code block’s JS. You wouldn’t want to do this in reality as eval() executes the code in the browser context, not a safe, sandboxed approach, but as a demo showing something like my code above which maps code blocks to output, I thought it could be handy:

https://stackblitz.com/edit/github-vawzfq4r?file=src%2Fcontent%2Fdocs%2Findex.mdx,src%2FInteractiveBlock.astro

From a glance at the runme docs, I’m not entirely clear how it would be used for your purpose, but hopefully this example is enough to point in the right direction on the Starlight side of things.

If you wanted to wrap the logic up into an Expressive Code plugin, that could allow you to avoid the extra wrapper component (e.g. triggering it with a keyword on the code block like ```sh runnable for example), but it’s a more advanced thing to do code-wise so I’d probably recommend the component approach for figuring out the initial implementation.

Useful plugin links:

• Expressive Code “Developing Plugins” guide
• Expressive Code plugin that is a good example for adding extra UI

[3goats]

Sorry for the delay - I've been away for a bit. Will take a look at this later today.