自 v1 迁移至 v2
将版本更新为 v2 的主要目标是：
- 更新 VitePress 至
1.0.0. - 确保所有集成，插件和模块和模块都遵循相同的代码结构、命名规则和导入/导出模式。
因此
- 所有更新的集成，插件和模块将不再与 VitePress RC 版本兼容。
- 所有更新的集成，插件和模块都将遵循以下规定：
- 如果是 Vue 组件、Vue 插件、客户端代码、样式等，导出的入口文件为
{packageName}/client。 - 如果是 i18n 模块，则导出入口文件为
{packageName}/locales。 - 如果是 VitePress 专用插件（如构建钩子、"buildEnd"、"transformHTML "等），则导出入口文件为
{packageName}/vitepress。 - 如果是 markdown-it 插件，则导出入口文件为
{packageName}/markdown-it。 - 如果是 Vite 插件，则导出入口文件为
{packageName}/vite。
- 如果是 Vue 组件、Vue 插件、客户端代码、样式等，导出的入口文件为
- 所有更新的集成，插件和模块都将遵循 Nolebase 集成，插件和模块的 i18n 指南。
- 所有更新的集成，插件和模块都将尝试复用
@nolebase/ui集成，插件和模块中的 Vue 组件。
由于将会引入破坏性改动，但是有迁移指南，迁移工作量较小。
行内链接预览
在 @nolebase/vitepress-plugin-inline-link-preview 插件中有一些破坏性更改。
- 不再需要使用
@nolebase/markdown-it-element-transform包进行标签转换，新的@nolebase/vitepress-plugin-inline-link-preview/markdown-it插件将导出所需的专用 markdown-it 插件。 - 按照新结构，新的
@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 包：
nun @nolebase/markdown-it-element-transformpnpm uninstall @nolebase/markdown-it-element-transformyarn remove @nolebase/markdown-it-element-transformnpm 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。
完整变更
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 插件中有一些破坏性更改。
- 按照新的结构，新的
@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 插件中有一些破坏性更改。
- 按照新的结构，新的
@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'基于 Git 的页面历史
1.includeDirs 和 includeExtensions 已被弃用并合并到 include 中，配置时，可以使用带有 ! 作为否定的 glob 匹配模式。 2.如果最终会被渲染的文件所对应的页面文件位于 VitePress 根目录（即 .vitepress所在目录）之外，请将 cwd（当前工作目录）配置为页面文件的父目录。(例如，在 Monorepo 中，如果需要读取 docs/ 以外的文件，则需要将 cwd 设置为 Monorepo 的根目录，而不是 VitePress 的根目录）。 3.不再需要配置 rewritePaths，因此 rewritePaths 已被弃用，可以安全删除。 4.rewritePaths 模式应配置为针对文件系统路径，而不是 URL 路由路径。
预览图片（社交媒体卡片）生成
在 @nolebase/vitepress-plugin-og-image 插件中有一些破坏性更改。
- 按照新的结构，新的
@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。
结论
- 按照新结构重写所有导入路径。
- 删除不再需要的旧包。
就是这样！除去这些以外，从 v1 迁移到 v2 应当不再有其他破坏性更改。
我们改进了代码结构、命名规则、导入/导出模式，使 Nolebase 生态系统中的包更加一致。
祝您写作愉快！🎉
我们在 v3 迁移指南中见！👋
贡献者
Neko
Northword