自 v1 迁移至 v2

字数

1399 字

阅读时间

7 分钟

将版本更新为 v2 的主要目标是：

1. 更新 VitePress 至 1.0.0.
2. 确保所有集成，插件和模块和模块都遵循相同的代码结构、命名规则和导入/导出模式。

因此

1. 所有更新的集成，插件和模块将不再与 VitePress RC 版本兼容。
2. 所有更新的集成，插件和模块都将遵循以下规定：
   • 如果是 Vue 组件、Vue 插件、客户端代码、样式等，导出的入口文件为 {packageName}/client。
   • 如果是 i18n 模块，则导出入口文件为 {packageName}/locales。
   • 如果是 VitePress 专用插件（如构建钩子、"buildEnd"、"transformHTML "等），则导出入口文件为 {packageName}/vitepress。
   • 如果是 markdown-it 插件，则导出入口文件为 {packageName}/markdown-it 。
   • 如果是 Vite 插件，则导出入口文件为 {packageName}/vite。
3. 所有更新的集成，插件和模块都将遵循 Nolebase 集成，插件和模块的 i18n 指南。
4. 所有更新的集成，插件和模块都将尝试复用 @nolebase/ui 集成，插件和模块中的 Vue 组件。

由于将会引入破坏性改动，但是有迁移指南，迁移工作量较小。

行内链接预览

在 @nolebase/vitepress-plugin-inline-link-preview 插件中有一些破坏性更改。

1. 不再需要使用 @nolebase/markdown-it-element-transform 包进行标签转换，新的 @nolebase/vitepress-plugin-inline-link-preview/markdown-it 插件将导出所需的专用 markdown-it 插件。
2. 按照新结构，新的 @nolebase/vitepress-plugin-inline-link-preview/client 将导出用于行内链接预览的 Vue 组件，而不是直接从包根目录导入。

移除 @nolebase/markdown-it-element-transform

{
  "devDependencies": {
    "@nolebase/markdown-it-element-transform": "^1.28.0"
  }
}

你可以执行以下步骤删除 @nolebase/markdown-it-element-transform 包：

@antfu/ni

nun @nolebase/markdown-it-element-transform

pnpm

pnpm uninstall @nolebase/markdown-it-element-transform

yarn

yarn remove @nolebase/markdown-it-element-transform

npm

npm uninstall @nolebase/markdown-it-element-transform

更新 VitePress 配置，以使用从 @nolebase/vitepress-plugin-inline-link-preview/markdown-it 导出的新 markdown-it 插件

你现在可以使用

import { defineConfig } from 'vitepress'
import { InlineLinkPreviewElementTransform } from '@nolebase/vitepress-plugin-inline-link-preview/markdown-it'

export default defineConfig({
  // ...
  markdown: {
    // ...
    config: (md) => {
      md.use(InlineLinkPreviewElementTransform) 
    },
  },
})

替代以前使用的 @nolebase/markdown-it-element-transform。

完整变更

.vitepress/config.ts

import { defineConfig } from 'vitepress'
import { ElementTransform } from '@nolebase/markdown-it-element-transform'
import type { Options as ElementTransformOptions } from '@nolebase/markdown-it-element-transform'
import { InlineLinkPreviewElementTransform } from '@nolebase/vitepress-plugin-inline-link-preview/markdown-it'

export default defineConfig({
  // ...
  markdown: {
    // ...
    config: (md) => {
      md.use(ElementTransform, (() => {
        let transformNextLinkCloseToken = false

        return { 
          transform(token) { 
            switch (token.type) { 
              case 'link_open': 
                if (token.attrGet('class') !== 'header-anchor') { 
                  token.tag = 'VPNolebaseInlineLinkPreview'
                  transformNextLinkCloseToken = true
                }

                break
              case 'link_close': 
                if (transformNextLinkCloseToken) { 
                  token.tag = 'VPNolebaseInlineLinkPreview'
                  transformNextLinkCloseToken = false
                } 

                break
            } 
          }, 
        } as ElementTransformOptions
      })()) 

      md.use(InlineLinkPreviewElementTransform) 
    },
  },
})

更新 VitePress 主题配置，以使用从 @nolebase/vitepress-plugin-inline-link-preview/client 导出的新 Vue 组件

由于现在所有 Vue 组件都是从 client 入口文件导出的，因此现在可以使用

import {
  NolebaseInlineLinkPreviewPlugin,
} from '@nolebase/vitepress-plugin-inline-link-preview'
} from '@nolebase/vitepress-plugin-inline-link-preview/client'

来替换以前的 @nolebase/vitepress-plugin-inline-link-preview。

样式也是一样的需要更新修改为从 client 导入：

import '@nolebase/vitepress-plugin-inline-link-preview/dist/style.css'
import '@nolebase/vitepress-plugin-inline-link-preview/client/style.css'

阅读增强

在 @nolebase/vitepress-plugin-enhanced-readabilities 插件中有一些破坏性更改。

1. 按照新的结构，新的 @nolebase/vitepress-plugin-enhanced-readabilities/client 将导出阅读增强的 Vue 组件，而不是直接从包根目录导入。

更新 VitePress 主题配置，以使用从 @nolebase/vitepress-plugin-enhanced-readabilities/client 导出的新 Vue 组件

由于现在所有 Vue 组件都是从 client 入口文件导出的，因此现在可以使用

import {
  InjectionKey as NolebaseEnhancedReadabilitiesInjectionKey,
  LayoutMode as NolebaseEnhancedReadabilitiesLayoutMode,
  NolebaseEnhancedReadabilitiesMenu,
  NolebaseEnhancedReadabilitiesScreenMenu,
} from '@nolebase/vitepress-plugin-enhanced-readabilities'
} from '@nolebase/vitepress-plugin-enhanced-readabilities/client'

来替换以前的 @nolebase/vitepress-plugin-enhanced-readabilities。

样式也是一样的需要更新修改为从 client 导入：

import '@nolebase/vitepress-plugin-enhanced-readabilities/dist/style.css'
import '@nolebase/vitepress-plugin-enhanced-readabilities/client/style.css'

闪烁高亮当前的目标标题

在 @nolebase/vitepress-plugin-highlight-targeted-heading 插件中有一些破坏性更改。

1. 按照新的结构，新的 @nolebase/vitepress-plugin-highlight-targeted-heading/client 将导出用于高亮目标标题的 Vue 组件，而不是直接从包根目录导入。

更新 VitePress 主题配置，以使用从 @nolebase/vitepress-plugin-highlight-targeted-heading/client 导出的新 Vue 组件

由于现在所有 Vue 组件都是从 client 入口文件导出的，因此现在可以使用

import {
  NolebaseHighlightTargetedHeading,
} from '@nolebase/vitepress-plugin-highlight-targeted-heading'
} from '@nolebase/vitepress-plugin-highlight-targeted-heading/client'

来替换以前的 @nolebase/vitepress-plugin-highlight-targeted-heading。

样式也是一样的需要更新修改为从 client 导入：

import '@nolebase/vitepress-plugin-highlight-targeted-heading/dist/style.css'
import '@nolebase/vitepress-plugin-highlight-targeted-heading/client/style.css'

预览图片（社交媒体卡片）生成

在 @nolebase/vitepress-plugin-og-image 插件中有一些破坏性更改。

1. 按照新的结构，新的 @nolebase/vitepress-plugin-og-image/vitepress 将导出 VitePress 专用插件，而不是从包根目录直接导入。

更新 VitePress 配置，以使用从 @nolebase/vitepress-plugin-og-image/vitepress 导出的新 VitePress 专用插件

你现在可以使用

import { buildEndGenerateOpenGraphImages } from '@nolebase/vitepress-plugin-og-image'
import { buildEndGenerateOpenGraphImages } from '@nolebase/vitepress-plugin-og-image/vitepress'

来替换以前使用的 @nolebase/vitepress-plugin-og-image。

结论

1. 按照新结构重写所有导入路径。
2. 删除不再需要的旧包。

就是这样！除去这些以外，从 v1 迁移到 v2 应当不再有其他破坏性更改。

我们改进了代码结构、命名规则、导入/导出模式，使 Nolebase 生态系统中的包更加一致。

祝您写作愉快！🎉

我们在 v3 迁移指南中见！👋

贡献者

Neko

文件历史

最后编辑于 4 天前查看完整历史

v2.0.0-rc3

50fbc-feat(og-image): migrated to /vitepress entry (#165)