fix(types): separate out deprecated highlight overload (#3987)

Minor thing in the type definitions I noticed. The .js makes it clear that the old API looks like `highlight(lang, code, ignoreIllegals)`, and the new API looks like `highlight(code, {lang, ignoreIllegals})`.

The types on the other hand imply you could do things like `highlight(code, {lang: ...}, true)` - but that `true` would be ignored at runtime.

So this separates the two forms into function overloads, and adds a `/** @deprecated */` tag to the old form so IDEs will hint not to use it.

CHANGES.md

@@ -41,6 +41,7 @@ Developer Tool:
 
 - enh(tools): order CSS options picklist [David Schach][]
 - enh(tools): remove duplicate CSS options [David Schach][]
+- (typescript): deprecate old `highlight` API [Misha Kaletsky][]
 
 Themes:
 
@@ -279,6 +280,7 @@ Grammars:
 [Mousetail]: https://github.com/mousetail
 [Gabriel Gonçalves]: https://github.com/KTSnowy
 [Nikita Sobolev]: https://github.com/sobolevn
+[Misha Kaletsky]: https://github.com/mmkal
 
 ## Version 11.5.0
 

types/index.d.ts

@@ -29,7 +29,9 @@ declare module 'highlight.js' {
     }
 
     interface PublicApi {
-        highlight: (codeOrLanguageName: string, optionsOrCode: string | HighlightOptions, ignoreIllegals?: boolean) => HighlightResult
+        highlight(code: string, options: HighlightOptions): HighlightResult
+        /** @deprecated use `higlight(code, {lang: ..., ignoreIllegals: ...})` */
+        highlight(languageName: string, code: string, ignoreIllegals?: boolean): HighlightResult
         highlightAuto: (code: string, languageSubset?: string[]) => AutoHighlightResult
         highlightBlock: (element: HTMLElement) => void
         highlightElement: (element: HTMLElement) => void