# docsify-shiki

[![](https://data.jsdelivr.com/v1/package/npm/@sy-records/docsify-shiki/badge)](https://www.jsdelivr.com/package/npm/@sy-records/docsify-shiki)
[![](https://img.shields.io/npm/v/@sy-records/docsify-shiki.svg?style=flat-square)](https://www.npmjs.com/package/@sy-records/docsify-shiki)
[![](https://img.shields.io/npm/l/@sy-records/docsify-shiki)](https://github.com/sy-records/docsify-shiki/blob/main/LICENSE)
[![Test](https://github.com/sy-records/docsify-shiki/actions/workflows/test.yml/badge.svg)](https://github.com/sy-records/docsify-shiki/actions/workflows/test.yml)

A docsify plugin for syntax highlighting with [Shiki](https://shiki.style).

Shiki generates inline styles for tokens, so you do not need to load a separate syntax theme CSS file.

## Usage

Load docsify and this plugin:

```html
<script>
  window.$docsify = {
    shiki: {
      theme: 'github-light',
      url: 'https://esm.run/shiki@3/bundle/web',
    },
  };
</script>
<script src="//cdn.jsdelivr.net/npm/docsify/dist/docsify.min.js"></script>
<script src="//cdn.jsdelivr.net/npm/@sy-records/docsify-shiki@1/dist/index.min.js"></script>
```

Then write normal fenced code blocks:

````markdown
```js
const answer = 42;
```
````

## Options

```js
window.$docsify = {
  shiki: {
    theme: 'github-dark',
    url: 'https://esm.run/shiki@3/bundle/web',
    langs: ['html', 'css', 'javascript', 'typescript', 'bash'],
    warnOnError: true,
  },
};
```

Available options:

- `theme`: Theme passed to `codeToHtml()`. Defaults to `github-light`.
- `themes`: Themes loaded when the plugin creates a highlighter.
- `langs`: Languages loaded when the plugin creates a highlighter. This does not remove the language importers exposed by a bundled Shiki entry.
- `url`: ESM URL imported by the plugin when no highlighter is provided. Defaults to `https://esm.run/shiki@3/bundle/web`.
- `highlighter`: A Shiki highlighter, a promise for one, or a function returning one.
- `load`: A function returning a Shiki module or highlighter.
- `defaultLanguage`: Language used when a code block has no language. Defaults to `text`.
- `codeToHtmlOptions`: Additional options merged into each `codeToHtml()` call.
- `transform`: Function called with each highlighted HTML string before it is inserted.
- `warnOnError`: Set to `true` to log Shiki loading or highlighting failures.

## Best performance

The default `url` uses Shiki's web bundle, which is lighter than the full
bundle but still exposes many language and theme importers. For the smallest
network graph, follow Shiki's best-performance guide and use fine-grained
modules with the JavaScript regex engine:

```html
<script>
  window.$docsify = {
    shiki: {
      theme: 'github-dark',
      load() {
        return Promise.all([
          import('https://esm.run/@shikijs/core@3'),
          import('https://esm.run/@shikijs/engine-javascript@3'),
          import('https://esm.run/@shikijs/themes@3/github-dark'),
          import('https://esm.run/@shikijs/langs@3/javascript'),
          import('https://esm.run/@shikijs/langs@3/typescript'),
          import('https://esm.run/@shikijs/langs@3/bash'),
          import('https://esm.run/@shikijs/langs@3/markdown'),
        ]).then(function (modules) {
          return modules[0].createHighlighterCore({
            themes: [modules[2].default],
            langs: [
              modules[3].default,
              modules[4].default,
              modules[5].default,
              modules[6].default,
            ],
            engine: modules[1].createJavaScriptRegexEngine(),
          });
        });
      },
    },
  };
</script>
```

## Reusing a highlighter

If you already load Shiki yourself, pass a highlighter:

```html
<script type="module">
  import { createHighlighter } from 'https://esm.run/shiki@3/bundle/web';

  window.$docsify = {
    shiki: {
      theme: 'github-dark',
      highlighter: createHighlighter({
        themes: ['github-dark'],
        langs: ['javascript', 'typescript', 'bash'],
      }),
    },
  };
</script>
```

## Styling

Shiki provides token colors and background colors inline. Add CSS only for layout details if needed:

```html
<style>
  .markdown-section pre.shiki {
    padding: 1rem;
    overflow: auto;
    border-radius: 6px;
  }

  .markdown-section pre.shiki code {
    background: transparent;
  }
</style>
```