镜像站点 · 本页由第三方 GitHub 只读镜像提供,非 GitHub 官方站点,不接受任何登录或凭据输入。前往 github.com
Skip to content

Improve example for invoking highlight.js - #1603

Merged
styfle merged 1 commit into
markedjs:masterfrom
octogonz:octogonz/fix-highlight.js
Feb 14, 2020
Merged

styfle merged 1 commit into
markedjs:masterfrom
octogonz:octogonz/fix-highlight.js

Conversation

@octogonz

@octogonz octogonz commented Feb 13, 2020 •

Copy link
Copy Markdown
Contributor

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

vercel Bot commented Feb 13, 2020 •

Copy link
Copy Markdown

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 styfle left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Great, thanks!

@styfle
styfle merged commit 6ae3651 into markedjs:master Feb 14, 2020
@UziTech UziTech mentioned this pull request Mar 6, 2020
11 of 12 tasks
tn0ms pushed a commit to warashibe/marked that referenced this pull request May 27, 2026

This branch was successfully deployed

1 active deployment
Preview — 6472717e Deployed Feb 13, 2020 by vercel[bot]
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

category: docs Documentation changes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants