This issue is to decide how we will represent, in Markdown, blocks containing example code. I think it should be pretty obvious in general but it's worth going through the details, and you never know.

Currently we use <pre> blocks of course, with classes for syntax highlighting:

<pre class="brush: js">
...
</pre>

In Markdown we can use fenced code blocks for this. The nice thing about these is that you can have an "info string" after the opening fence. From the GFM spec:

The first word of the info string is typically used to specify the language of the code sample, and rendered in the class attribute of the code tag

So we can use the first word to identify the language:

```js
const x = 1;
```

=>

<pre class="brush: js">const x = 1;
</pre>

We use other classes in code blocks, and the obvious suggestion is to support them, too, by putting them in the info string:

```js fee fi fo fum
const x = 1;
```

=>

<pre class="brush: js fee fi fo fum">const x = 1;
</pre>

But we might want to take the opportunity to clean things out a bit here. A quick survey of the JS docs yields the following classes on code blocks, in addition to language classes:

• example-good
• example-bad
• highlight[x,y,z]
• line-numbers
• no-line-numbers
• hidden

example-good and example-bad

Style this as a good/bad example (e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Errors/Illegal_character#mismatched_characters).

This is used extensively in the JS docs (~350 usages) especially the error reference. We should probably keep it.

highlight[x,y,z]

Highlight the lines with the given line numbers.

This isn't currently working, nor is is documented at https://developer.mozilla.org/en-US/docs/MDN/Guidelines/CSS_style_guide. Sometimes (about half the time apparently) people do highlight:[x,y,z], and because it's broken and undocumented, I don't know which is correct.

So for those reasons, although it does seem to be used several hundred times in our docs, I'd vote to discard it.

line-numbers and no-line-numbers

I count ~49 instances of line-numbers and ~500 instances of no-line-numbers across our docs. It doesn't seem to work, we seem to get no line numbers either way. I would like to discard this, and personally I like not having line numbers.

But if we want to have line numbers for some examples, we need a way to switch if off especially for syntax box-type code blocks (e.g. https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/slice#syntax).

hidden

Don't render the block.

I think we need hidden for code blocks in live samples, where people want the code to contribute to the live sample but don't want to show it (for example, for a bit of CSS to make the example look nicer - although we might argue that it would be better and more consistent for our examples to use common styles by default...).

But actually all the (several hundred) examples of this I can find that relate to live samples use it on a <div>, not a code block. For example, like this:

I'll talk about the general usage of hidden on <div> in another issue, but for live samples, I wonder if we'll need to do some conversion like: if you see <div class="hidden">, then apply hidden to all code blocks in that <div>.