Preview

Dark & Light Theme

| | | | --------------------------------- | ------------------------------- |

Transformers Preview

For a live preview, see my blog.

Install

bun i hexo-shiki-highlight

Add the following to your Hexo _config.yml:

syntax_highlighter: shiki

If you want to customize the highlighter, add a shiki section to _config.yml:

shiki:
  code_collapse:
    enable: true # Enable code collapse feature. Default: true
    max_lines: 20 # Max lines before collapsing. Default: 20
    show_lines: 10 # Lines to show when collapsed. Default: 10

  exclude_languages: ["mermaid"] # Languages excluded from Shiki highlighting
  enable_transformers: true

toolbar_items

You can configure which items to show in the code block toolbar:

shiki:
  toolbar_items:
    lang: true
    title: true
    wrapToggle: true
    copyButton: true
    shrinkButton: true # toggle code collapse/expand

language_aliases

This option allows you to define aliases for language names.

For example, to map conf to nginx and gitconfig to ini, you can use:

shiki:
  language_aliases:
    conf: nginx
    gitconfig: ini

After this configuration, code blocks marked with conf or gitconfig will be highlighted using the nginx and ini syntax rules, respectively.

style_to_class transformer

You can enable style_to_class to convert Shiki's inline styles into CSS classes. Example configuration:

shiki:
  style_to_class:
    enable: true
    class_prefix: _sk_

What this does:

• When enabled, inline style attributes produced by Shiki are transformed into unique class names.
• The class names are generated from a hash of the style object; use class_prefix to set a custom prefix for those class names.
• A CSS file containing these generated class rules will be written to the ~/Download directory.
• You must add a link to the generated CSS in your blog (for example in your theme's head) to apply the styles.

Here is an example of the difference in output

/* without style_to_class */
<span
  style="
    color: #d20f39;
    --shiki-light-font-style: italic;
    --shiki-dark: #f38ba8;
    --shiki-dark-font-style: italic;
    --shiki-tokyo: #c0caf5;
    --shiki-tokyo-font-style: italic;
  "
>
  Italic
</span>

/* with style_to_class */
<span class="_sk_1a2b3c">Italic</span>

This feature can help reduce HTML size, improve caching, and make it easier to customize styles via CSS.

Themes

Default themes: catppuccin-latte (light) and catppuccin-mocha (dark). You can define multiple themes for different modes, e.g.:

shiki:
  themes:
    light: "catppuccin-latte"
    dark: "catppuccin-mocha"
    tokyo: "tokyo-night"

The plugin may emit spans like:

<span style="color:#1E66F5;--shiki-dark:#89B4FA;--shiki-tokyo:#7AA2F7"
  >name</span
>

This plugin automatically switches to the dark theme when the page root has either:

• data-theme="dark" or data-theme="night"
• class="dark" or class="night"

For other theme-switching strategies, add your own logic.

Supported themes and languages are listed at Shiki Themes and Shiki Languages.

Use your own CSS

You can provide a custom CSS file to replace the default styles:

shiki:
  custom_css: "css/shiki-custom.css" # relative to `themes/<your_theme>/source`

Dev

For development, clone the repo and link it locally:

git clone https://github.com/Efterklang/hexo-shiki-highlight.git ~/Projects/hexo-dev/hexo-shiki-highlight
cd path_to_your_hexo_blog
bun i ~/Projects/hexo-dev/hexo-shiki-highlight
hexo clean
hexo s

Thanks

• nova1751/hexo-shiki-plugin
• HPCesia/hexo-highlighter-shiki
• gxt-kt/hexo-plugin-shiki