"includeExplanation" missing from types on both codeToHtml and codeToTokens

[pixeloution]

Validations

• Follow our Code of Conduct
• Read the Contributing Guide.
• Check that there isn't already an issue that reports the same bug to avoid creating a duplicate.

Describe the bug

Setting the "includeExplanation" option to true on codeToHtml works as expected but typescript does not recognize it as a valid property. This only causes an error if you use an object literal in the argument, for example:

// typescript error:
// error TS2353: Object literal may only specify known properties, and 'includeExplanation' 
// does not exist in type 'CodeToHastOptions<BundledLanguage, BundledTheme>'
shiki.codeToHtml(code, {
  lang: 'md',
  includeExplanation: true
});

Current workaround, should anyone see this thread before a fix exists, it to simply typecast:

shiki.codeToHtml(code, {
  lang: 'md',
  includeExplanation: true
} as CodeToHastOptions);

I'm unable to provide a patch at this time but the fix is straightforward.

Reproduction

See typescript example above

Contributes

• I am willing to submit a PR to fix this issue
• I am willing to submit a PR with failing tests

[antfu]

Why do you need it? The reason it wasn't included because there in Hast/HTML here isn't a useful presentation for the extra scope informations

[pixeloution]

Hi @antfu - thanks for the reply. Only the typescript definition for type CodeToHastOptions is incorrect. The library will provide explanation data when the option is set.

I'm using it at the moment for a custom implementation which converts the inline styles to classes; the built-in styles-to-classes creates a class for the <pre> tag but none of the other inline styles are converted, currently.

Strictly speaking I don't need a fix as I've used a type assertion but it seemed to be a bug.

(unrelated: love the library)

[antfu]

the built-in styles-to-classes creates a class for the <pre> tag but none of the other inline styles are converted, currently.

That's weird, would be great if you could create another issue with reproduction to address that would be great.

Only the typescript definition for type CodeToHastOptions is incorrect.

Yeah, that's a valid point. Would you like to send a quick PR to fix it? Thanks!

[MichaelMakesGames]

I forgot I ran into this when I first worked on https://github.com/MichaelMakesGames/shiki-colorized-brackets. As a quick fix, I just cast the type, and that made it's way to this repo when I ported that to @shikijs/colorized-brackets:

shiki/packages/colorized-brackets/src/index.ts

Line 72 in b28cf13

(options as CodeToTokensOptions).includeExplanation ||= 'scopeName'

We can remove that type cast (and comment above it) with the same PR

[MichaelMakesGames]

Beyond includeExplanation, should CodeToHastOptions extend CodeToTokensOptions? Looking at the implementation of codeToHast, it passes in it's options to codeToTokens

shiki/packages/core/src/highlight/code-to-hast.ts

Line 47 in b28cf13

} = codeToTokens(internal, input, options)

so really any of those CodeToTokensOptions could be set on the options passed into codeToCast, and they would be respected