Improve example for invoking highlight.js

[octogonz]

Marked version: 0.8.0

Markdown flavor: n/a

Description

The marked docs show this usage for invoking highlight.js to perform syntax highlighting of code blocks:

marked.setOptions({
  renderer: new marked.Renderer(),
  highlight: function(code) {
    return require('highlight.js').highlightAuto(code).value;
  },
  pedantic: false,
  gfm: true,
  breaks: false,
  sanitize: false,
  smartLists: true,
  smartypants: false,
  xhtml: false
});

The markdown code blocks to be highlighted might look like these examples:

```sql
SELECT * FROM MY_TABLE;
```

```
This is plain text.
```

The documented usage has several serious flaws:

1. The code language (e.g. sql) is completely ignored; it is not passed to highlight.js

2. The highlightAuto() API causes highlight.js to perform the entire highlighting algorithm 184 times -- once for each supported language -- in order to determine the "best match." This is a potentially expensive approach which doesn't make sense as a recommended or default behavior.

3. As a result, the code block This is plain text gets wrongly highlighted as applescript (since is and text are keywords in that language). That's NOT what a typical Markdown author would expect.

This PR updates the docs to honor the requested language, and fall back to plaintext otherwise. Note that the highlight() API throws an error for an unrecognized language, so the fallback needs to be implemented manually.

Contributor

• Test(s) exist to ensure functionality and minimize regression (if no tests added, list tests covering this PR); or,
• no tests required for this PR.
• If submitting new feature, it has been documented in the appropriate places.

Committer

In most cases, this should be a different person than the contributor.

• Draft GitHub release notes have been updated.
• CI is green (no forced merge required).
• Merge PR

[vercel]

This pull request is being automatically deployed with ZEIT Now (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://zeit.co/markedjs/markedjs/6rqwcwe36
✅ Preview: https://markedjs-git-fork-octogonz-octogonz-fix-highlightjs.markedjs.now.sh

[styfle]

Great, thanks!