docsify-shiki

A docsify plugin for syntax highlighting with Shiki.

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:

<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:

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

Options

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:

<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:

<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:

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

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