Hexo Highlight Shiki

The latest version (v2.0.0+) is using latest shiki (v3.2.1+), and is esm only. This requires node >= 20.19.0 || >= 22.12.0 which supports require(esm).

Use shiki as code block highlighter instead of builtin highlight.js or prism.js.

Installation

Install this package with your favorite package manager.

# pnpm
pnpm add hexo-highlight-shiki

# npm
npm add hexo-highlight-shiki

# yarn
yarn add hexo-highlight-shiki

# bun
bun add hexo-highlight-shiki

Hexo Configuration

In hexo configuraion file _config.yml, you should find a syntax_highlighter field, set it to shiki.

syntax_highlighter: "shiki"

Also, set highlight and prismjs to false to disable them.

highlight: false
prismjs: false

Shiki Configuration

Simple Configuration

Add a shiki field in hexo configuration file _config.yml, and set the theme field to the theme you want to use.

shiki:
  theme: "github-light"

Dark Mode

Shiki supports dark mode now.

shiki:
   themes:
      dark: "github-dark"
      light: "github-light"

For more configuration options, see Custom Dark Mode and Custom Theme.

Advanced Configuration

Custom Language

Shiki supports custom languages. You can add a languages field in shiki configs, and set the name and path fields.

shiki:
  languages:
    - name: "custom"
      path: "path/to/custom.tmLanguage.json"

If your site only needs to highlight your custom language, you can set loadAllLanguages to false to disable loading all languages. See Load languages on demand for more details.

shiki:
  loadAllLanguages: false

Load languages on demand

Due to the restriction of hexo, this plugin uses shiki highlighter instance to highlight code synchronously.

Shiki highlighter instance only loads the languages you need, so you can add a loadLanguages field in shiki configs, and set the languages you want to load.

By default, this plugin will load all languages, which is pretty slow. You can list languages you need in language field and set loadLanguages to false to disable it.

shiki:
  languages:
    - javascript
    - html
    - css
  loadLanguages: false

Custom Dark Mode

By default, this plugin will use query selector to change the theme based on the system dark mode. You can set autoInjectCSS to class (default is query) to use class selector instead.

The default selector is html.dark. You can change it by darkSelector field.

shiki:
   autoInjectCSS: "class"
   darkSelector: "html.dark"

Custom Theme

You can use your custom theme by not using string, but an object with name and path fields.

The path should point to a textMate theme json file

shiki:
  theme:
    name: "custom"
    path: "path/to/custom.json"

shiki:
   themes:
      dark:
         name: "custom-dark"
         path: "path/to/custom-dark.json"
      light:
         name: "custom-light"
         path: "path/to/custom-light.json"