Skip to content

Commit

Permalink
docs(inline link preview): add vite config description for ssr
Browse files Browse the repository at this point in the history
  • Loading branch information
litingyes committed Sep 18, 2024
1 parent a02e003 commit 595f7c5
Show file tree
Hide file tree
Showing 2 changed files with 141 additions and 0 deletions.
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,76 @@ Therefore, for those `[]()` link markup and `<a>` elements you don't want to tra
1. Add `no-inline-link-preview` to the class list.
2. Assign a `data-inline-link-preview` attribute with the value of `false`.

### Add plugin-specific options into configurations of Vite

First of all, in VitePress's [**primary configuration file**](https://vitepress.dev/reference/site-config#config-resolution) (not this is not a **theme configuration file**, it's usually located at `docs/.vitepress/config.ts`, file paths and extensions may be vary), you need to supply some of the [Server-Side Rendering related options](https://vitejs.dev/guide/ssr.html#ssr-externals) in the root configuration object of [Vite](https://vitejs.dev).

Add the Inline Link Previewing plugin package name `@nolebase/vitepress-plugin-inline-link-preview` into the Vite options that required by VitePress to process this plugin:

<!--@include: @/pages/en/snippets/details-colored-diff.md-->

<!--@include: @/pages/en/snippets/configure-tsconfig.md-->

```typescript twoslash
import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
vite: { // [!code ++]
optimizeDeps: { // [!code ++]
exclude: [ // [!code ++]
'@nolebase/vitepress-plugin-inline-link-preview/client', // [!code ++]
], // [!code ++]
}, // [!code ++]
ssr: { // [!code ++]
noExternal: [ // [!code ++]
// If there are other packages that need to be processed by Vite, you can add them here. // [!code hl]
'@nolebase/vitepress-plugin-inline-link-preview', // [!code ++]
], // [!code ++]
}, // [!code ++]
}, // [!code ++]
lang: 'en',
title: 'Site Name',
themeConfig: {
// rest of the options...
}
// rest of the options...
})
```

You might have configured the separated [Vite configuration file](https://vitejs.dev/config/) (e.g. `vite.config.ts`) if you are already mastered Vite. In this case, you could ignore the above configuration and add the following configuration to your Vite configuration file:

<!--@include: @/pages/en/snippets/details-colored-diff.md-->

<!--@include: @/pages/en/snippets/configure-tsconfig.md-->

```typescript twoslash
import { defineConfig } from 'vite'

export default defineConfig(() => {
return {
optimizeDeps: {
exclude: [ // [!code ++]
'@nolebase/vitepress-plugin-inline-link-preview/client', // [!code ++]
'vitepress' // [!code ++]
], // [!code ++]
},
ssr: { // [!code ++]
noExternal: [ // [!code ++]
// If there are other packages that need to be processed by Vite, you can add them here. // [!code hl]
'@nolebase/vitepress-plugin-inline-link-preview', // [!code ++]
], // [!code ++]
}, // [!code ++]
plugins: [
// other vite plugins...
],
// other vite configurations...
}
})
```

If you haven't configured any of the separated [Vite configuration file](https://vitejs.dev/config/) (e.g. `vite.config.ts`) before but still want to have a try with the above configuration, you can create a `vite.config.ts` file in the root directory of your VitePress project and add the above configuration to it. (Don't forget to install `vite` through your package manager as well!)

### Integrate with VitePress

Since the `InlineLinkPreviewElementTransform` plugin will transform the `[]()` link markup or `<a>` elements into the `<VPNolebaseInlineLinkPreview>` elements, you need to install the `VPNolebaseInlineLinkPreview` component into your VitePress theme in order to render the inline link previewing UI.
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -77,6 +77,77 @@ export default defineConfig({
1. 在类列表中添加 `no-inline-link-preview`
2. 为标签添加一个 `data-inline-link-preview` 属性,并设置值为 `false`

### 添加 Vite 相关配置

首先,请在你的 VitePress [**核心配置文件**](https://vitepress.dev/reference/site-config#config-resolution) 中(注意不是**主题配置文件**,通常为 `docs/.vitepress/config.ts`,文件路径和拓展名也许会有区别)的根字段中添加 [Vite](https://vitejs.dev)[SSR 服务端渲染相关](https://cn.vitejs.dev/config/ssr-options.html#ssr-external) 的配置。

将行内链接预览的插件包 `@nolebase/vitepress-plugin-inline-link-preview` 添加到需要 VitePress 底层的 Vite 帮忙处理的依赖:

<!--@include: @/pages/zh-CN/snippets/details-colored-diff.md-->

<!--@include: @/pages/zh-CN/snippets/configure-tsconfig.md-->

```typescript twoslash
import { defineConfig } from 'vitepress'

// https://vitepress.dev/reference/site-config
export default defineConfig({
vite: { // [!code ++]
optimizeDeps: {
exclude: [ // [!code ++]
'@nolebase/vitepress-plugin-inline-link-preview/client', // [!code ++]
], // [!code ++]
},
ssr: { // [!code ++]
noExternal: [ // [!code ++]
// 如果还有别的依赖需要添加的话,并排填写和配置到这里即可 // [!code hl]
'@nolebase/vitepress-plugin-inline-link-preview', // [!code ++]
], // [!code ++]
}, // [!code ++]
}, // [!code ++]
lang: 'zh-CN',
title: '网站标题',
themeConfig: {
// 其他的配置...
}
// 其他的配置...
})
```

如果你很厉害,为 VitePress 的文档站点配置了分离和单独的 [Vite 配置文件](https://vitejs.dev/config/)(比如 `vite.config.ts`),那你也可以省略上面的配置,直接在 Vite 的配置文件中添加下面的配置:

<!--@include: @/pages/zh-CN/snippets/details-colored-diff.md-->

<!--@include: @/pages/zh-CN/snippets/configure-tsconfig.md-->

```typescript twoslash
import { defineConfig } from 'vite'

export default defineConfig(() => {
return {
optimizeDeps: {
exclude: [ // [!code ++]
'@nolebase/vitepress-plugin-inline-link-preview/client', // [!code ++]
'vitepress' // [!code ++]
], // [!code ++]
},
ssr: { // [!code ++]
noExternal: [ // [!code ++]
// 如果还有别的依赖需要添加的话,并排填写和配置到这里即可 // [!code hl]
'@nolebase/vitepress-plugin-inline-link-preview', // [!code ++]
], // [!code ++]
}, // [!code ++]
plugins: [
// 其他 Vite 插件配置...
],
// 其他的配置...
}
})

```

如果你在没有单独配置过 [Vite 配置文件](https://vitejs.dev/config/)(比如 `vite.config.ts`)的情况下想要直接复制上面的代码的话,只需要在 VitePress 站点所在的地方新建一个 `vite.config.ts` 即可,不过也记得还需要通过包管理器安装一下 `vite` 哦。

### 添加 VitePress 主题相关的配置

在 VitePress 的[**主题配置文件**](https://vitepress.dev/reference/default-theme-config#default-theme-config)中(注意不是**配置文件**,通常为 `docs/.vitepress/theme/index.ts`,文件路径和拓展名也许会有区别),**将行内链接预览插件的组件注册到 VitePress 主题中**
Expand Down

0 comments on commit 595f7c5

Please sign in to comment.