refactor highlight: add extend api for highlight

[stevenjoezhang]

What does it do?

Currently, there are 3 files relevant to code highlighting

lib/plugins/filter/before_post_render/backtick_code_block.js
lib/plugins/tag/code.js
lib/plugins/tag/include_code.js

Each file is hardcoded with support for highlight.js and prismjs, which would make it very difficult to support other code highlighting functions.

To make it more flexible, I propose a new highlight filter:

hexo.extend.highlight.register('highlight.js', highlighter);

declare function highlighter(code: string, options: {
  language?: string,
  meta?: string,
  highlightLines?: unknown, // TBD
  lineNumbers?: boolean,
  // ...
}): string

With this filter, developers can use custom code highlighting functions to replace the built-in highlight.js or prismjs.

Issue resolved: #1891 #1300 #4010 #1938

Usage

// _config.yml
highlighter: 'prismjs'

Screenshots

Pull request tasks

• Add test cases for the changes.
• Passed the CI test.

[github-actions]

Publish flamegraph to https://ffdeaee6503ad5877006576f59622fb7d91390cc-16-hexo.surge.sh/flamegraph.html

[coveralls]

Coverage increased (+0.09%) to 98.769% when pulling 46021e0 on highlight into 40df922 on master.

[renbaoshuo]

👍 LGTM

[stevenjoezhang]

Discussion: should we use filter api to support highlight event, or create a new hexo.extend.highlight api? See #4010 (comment)

CC @hexojs/core

[renbaoshuo]

I think we should use hexo.extend.filter.register('highlight', ...). Because code highlighting is a (sometimes optional) step in the article rendering process.

[stevenjoezhang]

Another difference is: other filters allow multiple callback functions to be registered per event, and callbacks are executed sequentially when the event is triggered. For code highlighting, only a single handler function should be registered. (For example, the user can choose either highlight.js or prism, but should not register both with hexo.extend.filter)

[SukkaW]

IMHO, the ideal design is that we have a new plugin API hexo.extend.highlight:

hexo.extend.highlight.register('highlight.js', highlighter);
hexo.extend.highlight.register('prismjs', highlighter);
hexo.extend.highlight.register('shiki', highlighter);

We can read _config.yml to determine which highlighter to use:

// _config.yml
highlight: 'shiki'

The highlighter should have an API interface like this:

declare function highlighter({
  code: string,
  language?: string,
  meta?: string,
  highlightLines?: unknown, // TBD
  lineNumbers?: boolean,
  // ...
}): string

[stevenjoezhang]

New API interface of highlighter:

declare function highlighter(code: string, options: {
  language?: string,
  meta?: string,
  highlightLines?: unknown, // TBD
  lineNumbers?: boolean,
  // ...
}): string

The types of two parameters are the same as require('hexo-util').highlight and require('hexo-util').prismHighlight

Besides, can I remove the following code? It seems to be dead code

hexo/lib/hexo/post.js

Line 409 in 871ac4f

if (!config.highlight.enable) options.highlight = null;

See also hexojs/hexo-renderer-marked#134 https://github.com/hexojs/hexo-renderer-marked/issue/26

[yoshinorin]

I suggested two comments, but basically LGTM. I think we can merge this.

[yoshinorin]

@stevenjoezhang

Would you please change the filename from lib/extend/highlight.js to lib/extend/syntaxhighlight.js ?

30403c1

[yoshinorin]

LGTM 🚀