Propose: Improve `highlight` API

For those finding there way here from the deprecation warning it’s easy to upgrade your code:

// The old API:
highlight(language, code, ignore_illegals, continuation) {
// The new API take an options object literal:
highlight(code, { language, ignoreIllegals}) {

So to upgrade your code:

// before
html = highlight("vbscript","your code goes here", true)
// after
html = highlight("your code goes here", {language: "vbscript", ignoreIllegals: true })

IE, just switch the order of the arguments and pass language and ignoreIllegals in the options object now.

---

Advantages:

• target of the verb [highlight] is now the first argument, which makes more sense, such as format(drive), highlight(code)
• no need to remember order of the arguments
• we can still support the old API for legacy (ie, non-breaking change)
• fewer arguments are generally better (easier to understand, now at the call site you always see the names of the optional arguments, etc)

Checklist:

• new highlight API as shown above
• <del>highlightAuto -> highlight(code)</del>
• <del>highlightAuto is deprecated</del>
• highlightBlock -> highlightElement #3003
• highlightBlock -> deprecated #3003
• fixMarkup -> deprecated, will be removed with v11
• initHighlightingOnLoad -> highlightAll()
• initHighlighting -> highlightAll()

[joshgoebel]

We may look into something like https://github.com/dougwilson/nodejs-depd#readme in the future. I’ll split your comment out into a new issue. I like the idea of per-callsite warnings, not just singular logging.

[mihkeleidast]

Would it maybe make sense to throttle logging the same deprecation messages? We’re using highlight.js as a dependency of another dependency so can’t directly update the deprecated code. The console is simply drowned in the exactly same deprecation message. Once would suffice, IMO, so we could alert the dependency to change it.