@shikijs/markdown-it

Shiki 的 markdown-it 插件。

安装

npm

npm i -D @shikijs/markdown-it

yarn

yarn add -D @shikijs/markdown-it

pnpm

pnpm add -D @shikijs/markdown-it

bun

bun add -D @shikijs/markdown-it

deno

deno add npm:@shikijs/markdown-it

使用

import Shiki from '@shikijs/markdown-it'
import MarkdownIt from 'markdown-it'

const md = MarkdownIt()

md.use(await Shiki({
  themes: {
    light: 'vitesse-light',
    dark: 'vitesse-dark',
  }
}))

转换器

你可以通过插件选项传入 transformers 来自定义高亮的代码。

import Shiki from '@shikijs/markdown-it'
import { transformerNotationDiff } from '@shikijs/transformers'
import MarkdownIt from 'markdown-it'

const md = MarkdownIt()

md.use(await Shiki({
  themes: {
    light: 'vitesse-light',
    dark: 'vitesse-dark',
  },
  transformers: [
    transformerNotationDiff(),
  ],
}))

细粒度包

默认情况下，将导入 shiki 的完整包。如果你使用的是细粒度包，你可以从 @shikijs/markdown-it/core 导入，并传入你自己的高亮器：

import { fromHighlighter } from '@shikijs/markdown-it/core'
import MarkdownIt from 'markdown-it'
import { createHighlighterCore } from 'shiki/core'
import { createOnigurumaEngine } from 'shiki/engine/oniguruma'

const highlighter = await createHighlighterCore({
  themes: [
    import('@shikijs/themes/vitesse-light')
  ],
  langs: [
    import('@shikijs/langs/javascript'),
  ],
  engine: createOnigurumaEngine(() => getWasm)
})

const md = MarkdownIt()

md.use(fromHighlighter(highlighter, { /* 选项 */ }))

使用简写

Shiki 的 简写 支持按需加载主题和语言，但这也使得高亮过程变成异步。不幸的是，markdown-it 本身 默认不支持异步高亮。

为了解决这个问题，你可以使用 Anthony Fu 的 markdown-it-async。Shiki 也提供了与其的集成，你可以从 @shikijs/markdown-it/async 导入 fromAsyncCodeToHtml。

import { fromAsyncCodeToHtml } from '@shikijs/markdown-it/async'
import MarkdownItAsync from 'markdown-it-async'
import { codeToHtml } from 'shiki' // 或你自定义的简写包

// 使用 markdown-it-async 初始化 MarkdownIt 实例
const md = MarkdownItAsync()

md.use(
  fromAsyncCodeToHtml(
    // 传入 codeToHtml 函数
    codeToHtml,
    {
      themes: {
        light: 'vitesse-light',
        dark: 'vitesse-dark',
      }
    }
  )
)

// 使用 `md.renderAsync` 替代 `md.render`
const html = await md.renderAsync('# Title\n```ts\nconsole.log("Hello, World!")\n```')

Transformer 注意事项

markdown-it 默认强制将 <pre><code> 作为代码块 HTML 的外层包裹。如果你使用自定义的 Shiki transformer，这种行为可能不符合预期。例如，如果 transformer 产生的是

<div class="fenced-code-block">
  <pre>
    <code>
      …
    </code>
  </pre>
</div>

经过 markdown-it 处理后的结果会是

<pre>
  <code>
    <div class="fenced-code-block">
      <pre>
        <code>
          …
        </code>
      </pre>
    </div>
  </code>
</pre>

你可以通过在自己的 markdown-it 配置中添加 olets/markdown-it-wrapperless-fence-rule，或者编写自己的 markdown-it fence 规则（参见 markdown-it#269）来规避该问题。