Instantsearch.js: Better control over runnable examples

[bobylito]

Right now, the JS script in the page relies on a test to define if the code of an example should be runnable or not: contains search.addWidget? or /function renderFn\(\S+(, isFirstRendering)?\) {/g.test(exampleContent)?

This gives poor control over what's runnable or not, which seems magical and also lead to inconsistent experience like the new calendar guide. In this guide, we have one runnable example while the others are not. Given the context, none should be runnable in the guide.

Options could be:

• have a way to specify runnable js
• have a front matter option for setting if the js examples on the page should be runnable

[Haroenv]

I think a comment or wrapping in a class should be a good enough metric do decide whether they're runnable. The credentials done via frontmatter as in #2690 seems good to me!

[francoischalifour]

Here are the solutions that I see with their pros and cons:

1. In the frontmatter

Example

---
title: My guide
runnable: false
---

Pros

• Easy to set up

Cons

• Make all code samples in the page not runnable (we might want to only disable one)

2. As a comment/annotation in the code itself

Example

````

@runnable
// code...

````

Pros

• Enable/disable a unique code sample

Cons

• We need to parse and remove it (not sure how easy it is yet)

3. As a new Markdown language

We can create an extension to our Markdown parser to create a runnable JavaScript language.

Example

````

// My code

````

Pros

• Enable/disable a unique code sample

Cons

• Need to create another parser
• We lose the IDE syntax highlighting

4. As an HTML Element

Example

<pre class="runnable">
  <code>
    // my code
  </code>
</pre>

Pros

• Enable/disable a unique code sample

Cons

• We lose all IDE syntax highlighting
• We lose syntax highlighting in the browser (since we cannot specify the language anymore as far as I know)

---

For now, I'd say that the frontmatter solution (1) is the easiest to implement.

[bobylito]

@francoischalifour I agree that 1 should good enough for now and it has a superior DX.

[Haroenv]

What I meant instead of 4:

<div class="runnable">

```js
console.log('hello there');
```

</div>

[francoischalifour]

Ah, got you, it works and would be easy to parse!

[bobylito]

So we got a solution with @Haroenv idea, @francoischalifour ? 👍 ?

[francoischalifour]

Yes! What default behavior do we want? (runnable or not runnable)

Having it not runnable by default would be annoying as we'd have to update most of the guides and docs.