快速上手

安装

通过运行以下命令将 @nolebase/vitepress-plugin-inline-link-preview 安装到您的项目依赖项中：

@antfu/ni

ni @nolebase/vitepress-plugin-inline-link-preview -D

pnpm

pnpm add @nolebase/vitepress-plugin-inline-link-preview -D

npm

npm install @nolebase/vitepress-plugin-inline-link-preview -D

yarn

yarn add @nolebase/vitepress-plugin-inline-link-preview -D

用法

将行内链接预览插件集成到 VitePress 项目中包括两个主要步骤：

1. 配置 markdown-it 插件（语法转换与数据处理相关配置）
2. 添加 VitePress 主题相关的配置（UI 显示相关配置）

配置 markdown-it 插件

首先，请在你的 VitePress 核心配置文件 中（注意不是主题配置文件，通常为 docs/.vitepress/config.ts，文件路径和拓展名也许会有区别）的根字段中，注册所需的 markdown-it 插件：

如果你未曾见过这种红色绿色的标记

这是一种用于在用户界面（UI）上展示差异对比的标记规则。

红色的部分是你需要删除的，通常也以「减号 -」来表示，或者你可以理解为：这行文本原本的模样；

绿色的部分是你需要添加的，通常也以「加号 +」来表示，或者你可以理解为：这行文本将会被修改为的模样。

如果你想要了解更多有关「差异对比」的知识，你可以查看这篇有关 diffutils 历史的英文回答和 Git 的文档

是 TypeScript 用户吗？

至少需要配置下面的几个选项：

{
  "compilerOptions": {
    "module": "ESNext", 
    "moduleResolution": "Bundler", 
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

其中的

• module 选项指定了 JavaScript/TypeScript 的模块格式，Nolebase Integrations 默认使用与 ESNext 相兼容的模块格式。
• moduleResolution 选项指定了模块解析策略，因为所有的 Nolebase Integrations 插件都遵循最新的 ECMAScript 规范与导出声明，如果你遇到了 Cannot find module ... or its corresponding type declarations 的错误，你可能需要将 moduleResolution 设置为 Bundler。

如果你想要更多的配置，可以参考下面的示例：

{
  "compilerOptions": {
    "jsx": "preserve",
    "lib": [
      "DOM",
      "ESNext"
    ],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "resolveJsonModule": true,
    "strict": true,
    "strictNullChecks": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noEmit": true,
    "removeComments": false,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

typescript

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

// https://vitepress.dev/reference/site-config
export default ({
  : 'en',
  : 'Site Name',
  : {
    // 剩余的选项...
  },
  : { 
    () { 
      // 其他 markdown-it 配置...
      .() 
    } 
  } 
  // 剩余的选项...
})

在幕后，InlineLinkPreviewElementTransform 是一个 markdown-it 插件，可直接将 []() 链接语法与 <a> 元素转换为 <VPNolebaseInlineLinkPreview> 元素（也就是行内链接预览组件）。

默认情况下，该 markdown-it 插件将转换所有符合以下条件的 []() 链接语法或 <a> 元素：

1. 不包含 header-anchor 类。
2. 不包含no-inline-link-preview 类。
3. 具有 data-inline-link-preview="false" 属性。

因此，对于那些你不想转换成 <VPNolebaseInlineLinkPreview> 的 []() 链接标记和 <a> 元素，你可以：

1. 在类列表中添加 no-inline-link-preview。
2. 为标签添加一个 data-inline-link-preview 属性，并设置值为 false。

添加 VitePress 主题相关的配置

在 VitePress 的主题配置文件中（注意不是配置文件，通常为 docs/.vitepress/theme/index.ts，文件路径和拓展名也许会有区别），将行内链接预览插件的组件注册到 VitePress 主题中：

如果你未曾见过这种红色绿色的标记

这是一种用于在用户界面（UI）上展示差异对比的标记规则。

红色的部分是你需要删除的，通常也以「减号 -」来表示，或者你可以理解为：这行文本原本的模样；

绿色的部分是你需要添加的，通常也以「加号 +」来表示，或者你可以理解为：这行文本将会被修改为的模样。

如果你想要了解更多有关「差异对比」的知识，你可以查看这篇有关 diffutils 历史的英文回答和 Git 的文档

是 TypeScript 用户吗？

至少需要配置下面的几个选项：

{
  "compilerOptions": {
    "module": "ESNext", 
    "moduleResolution": "Bundler", 
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

其中的

• module 选项指定了 JavaScript/TypeScript 的模块格式，Nolebase Integrations 默认使用与 ESNext 相兼容的模块格式。
• moduleResolution 选项指定了模块解析策略，因为所有的 Nolebase Integrations 插件都遵循最新的 ECMAScript 规范与导出声明，如果你遇到了 Cannot find module ... or its corresponding type declarations 的错误，你可能需要将 moduleResolution 设置为 Bundler。

如果你想要更多的配置，可以参考下面的示例：

{
  "compilerOptions": {
    "jsx": "preserve",
    "lib": [
      "DOM",
      "ESNext"
    ],
    "module": "ESNext",
    "moduleResolution": "Bundler",
    "resolveJsonModule": true,
    "strict": true,
    "strictNullChecks": true,
    "noFallthroughCasesInSwitch": true,
    "noImplicitAny": true,
    "noUnusedLocals": true,
    "noUnusedParameters": true,
    "noEmit": true,
    "removeComments": false,
    "esModuleInterop": true,
    "forceConsistentCasingInFileNames": true,
    "isolatedModules": true,
    "verbatimModuleSyntax": true,
    "skipLibCheck": true
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

.vitepress/theme/index.ts

import {  } from 'vue'
import  from 'vitepress/theme'
import type {  as ThemeConfig } from 'vitepress'
import { 
  , 
} from '@nolebase/vitepress-plugin-inline-link-preview/client'

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

export const : ThemeConfig = {
  : ,
  : () => {
    // 其他配置...
  },
  ({  }) { 
    .() 
  }, 
}

export default 

错误排查

遭遇了 Cannot find module ... or its corresponding type declarations 错误？

如果有任何的 Nolebase Integrations 插件在 .ts 或 .vue 文件中出现此错误，你可能需要在 tsconfig.json 文件中配置 moduleResolution 选项：

{
  "compilerOptions": {
    "module": "ESNext", 
    "moduleResolution": "Bundler", 
  },
  "include": [
    "**/.vitepress/**/*.ts",
    "**/.vitepress/**/*.mts",
    "**/.vitepress/**/*.vue"
  ],
  "exclude": [
    "node_modules"
  ]
}

如果错误仍然存在，请提交 GitHub issue 以获得进一步帮助并排除故障。

贡献者

Neko

godkun

页面历史

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

ed0b1-docs: incorrect import path for style.css (#186)

52672-docs: refined docs

0227c-feat(enhanced-readabilities): migrate to use unbuild (#161)

e00b9-feat(git-changelog): added i18n capabilities, added more fancy documentations (#156)

e690e-docs: refactored docs to better guide users