Skip to content

迁移

Shiki 的 v1.0 版本是一次重大重写,我们借此机会修改了过去的所有设计决定。我们原本有一个独立的软件包名称 Shikiji,用来试验新的设计,现在合并回 Shiki,成为 v1.0。

从 v0.14 迁移

shiki@0.14.3 相比,破坏性更改列表内容如下:

硬性破坏性改动

你必须手动迁移的破坏性改动:

  • CJS 和 IIFE 构建被移除。查看 使用 CJS使用 CDN 获取更多详细信息。
  • codeToHtml 在内部使用了 hast。 生成的 HTML 会略有不同,但行为一致。
  • 不支持 css-variables 主题。请使用 双主题,或在 主题颜色控制 查看更多。

软性破坏性改动

shiki 包中包含的破坏性改动,而 兼容构建 @shikijs/compat 中不具备(屏蔽):

  • 顶级命名导出项 setCDNloadLanguageloadThemesetWasm 被移除,因为其不再被需要。
  • BUNDLED_LANGUAGESBUNDLED_THEMES 被移动至 shikiji/langsshikiji/themes 中并分别更名为 bundledLanguagesbundledThemes
  • getHighlightertheme 选项被移除,请改用数组形式的 themes
  • 高亮器不再具有内部的默认主题上下文。 对于 codeToHtmlcodeToThemedTokenstheme 选项是必须的。
  • codeToThemedTokens 更名为 codeToTokensBase,并添加了一个更高级的 codeToTokens
  • codeToTokens 默认情况下将 includeExplanation 设置为 false
  • .ansiToHtml 作为一个特殊的语言 ansi 被合并至 .codeToHtml。请使用 .codeToHtml(code, { lang: 'ansi' })
  • lineOptions 被移除,取而代之的是完全可定制的 transforms 选项。
  • LanguageRegistrationgrammar 字段被展开到 LanguageRegistration 本身,参考类型定义获取详细信息。

生态包

  • shiki-twoslash 完全重写。它不再是 Shiki 高亮器的包装,而是一个可以插入任何支持转换器的集成的 Shiki 转换器,以 @shikijs/twoslash 出现。
  • shiki-twoslash 的集成,例如 gatsby-remark-shiki-twoslash etc, 等,会逐渐迁移到通用的 Shiki 版本。在此之前,你可以使用 @shikijs/rehype@shikijs/markdown-it 来将 Shiki 集成元框架。
  • 引入了新的官方集成,如 @shikijs/monaco@shikijs/cli@shikijs/rehype 以及 @shikijs/markdown-it
  • shiki-renderer-pathshiki-renderer-svg 使用频率较低,现已被废弃。如果你需要它们,请发起一个 issue,并带上你的用例,我们会很乐意将它们再加回来。
  • 由于已经不再建议使用 VuePress,所以 vuepress-plugin-shiki 已被废弃。它的继承者 VitePress 具有内建的 Shiki 集成。

从 Shikiji 迁移

如果你已经在使用 Shikiji,请确保你使用的是最新的次版本 v0.10。然后重新命名软件包,这个迁移的过程应该会非常简单:

  • shikiji -> shiki
  • shikiji-core -> @shikijs/core
  • shikiji-twoslash -> @shikijs/twoslash
  • shikiji-transformers -> @shikijs/transformers
  • shikiji-monaco -> @shikijs/monaco
  • shikiji-cli -> @shikijs/cli
  • markdown-it-shikiji -> @shikijs/markdown-it
  • rehype-shikiji -> @shikijs/rehype

以 MIT 许可证发布