Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(inline link preview): add vite config description for ssr #310

Merged
merged 1 commit into from
Sep 18, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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
Loading