Add documentation for CodeBlock to describe className prop

[andrewnicols]

Have you read the Contributing Guidelines on issues?

• I have read the Contributing Guidelines on issues.

Description

Looking through the source for the codeBlock I see that it's possible to add classes to the codeBlock.

This is useful as we'd like to add line numbering to our code blocks, but would also like the ability to selectively enable or disable it.

Ideally line numbering should be a top-level feature fo the CodeBlock, but as it is not currently we can do this with some fairly simple css:

/* Reset line numbers for each new code block */
.prism-code {
    counter-reset: line-number;
}

:not(
.theme-code-block:not(.no-line-numbers) .prism-code.language-js .token-line::before,
.theme-code-block:not(.no-line-numbers) .prism-code.language-mustache .token-line::before,
.theme-code-block:not(.no-line-numbers) .prism-code.language-html .token-line::before,
.theme-code-block:not(.no-line-numbers) .prism-code.language-php .token-line::before,
.theme-code-block.force-line-numbers .prism-code .token-line::before {
  counter-increment: line-number;
  content: counter(line-number);
  margin-right: calc(var(--ifm-pre-padding) * 1.5);
  text-align: right;
  min-width: 2.5rem;
  display: inline-block;
  opacity: .3;
  position: sticky;
  left: var(--ifm-pre-padding);
}

This then allows me to have a code block:

``` title="Forcibly add line numbers" className=force-line-numbers
Unidentified language with line numbers forced
```

And

```js title="Prevent line numbers from a language which has them ordinarily" className=no-line-numbers
No line numbers here
```

I'm happy to help document this if you feel it's worthwhile having.

Self-service

• I'd be willing to address this documentation request myself.

[Josh-Cena]

It's a bit tricky, because for title="...", we parse this ourselves, so those quotes don't get into the final props; but MDX doesn't remove the quotes, so className="no-line-numbers" would become class="language-js \"no-line-numbers\"". I'm a bit afraid that it would only be confusing for others, since we actually never offered this API in the first place.

We would make line numbers opt-in in #7007, FYI

[andrewnicols]

Hi Josh,

That makes sense. I had noticed that the quotes were included in the generated class name.

I'd suggest that #7007 also provides a way to make line numbers enabled-by-default (at least for certain langauges) and opt-out in those cases too, but that may be better as a separate PR.

Thanks

[Josh-Cena]

Thanks for understanding. For default-true line numbering, I'm not very much in favor of adding another theme config option, but we can certainly talk about that after #7007