From ed0e0235aa492133dc45bb301a4fc508c1066ae1 Mon Sep 17 00:00:00 2001 From: Neko Ayaka Date: Tue, 12 Dec 2023 21:23:30 +0800 Subject: [PATCH 1/3] fix: highlighting not working when page route changes Signed-off-by: Neko Ayaka --- .../index.md | 70 ++++++++++++++++++- .../index.md | 66 +++++++++++++++++ .../components/HighlightTargetedHeading.vue | 11 ++- .../vite.config.ts | 3 + 4 files changed, 147 insertions(+), 3 deletions(-) diff --git a/docs/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/index.md b/docs/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/index.md index 50e44f80..7be0fe1b 100644 --- a/docs/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/index.md +++ b/docs/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/index.md @@ -61,9 +61,75 @@ yarn add @nolebase/vitepress-plugin-highlight-targeted-heading ::: -### Configure for VitePress +### Integrate with VitePress -In VitePress's [**theme configuration file**](https://vitepress.dev/reference/default-theme-config#default-theme-config) (note that it's not a **configuration file**, it's usually located at `docs/.vitepress/theme/index.ts`, file paths and extensions may be vary), import `@nolebase/vitepress-plugin-enhanced-readabilities` import and add it to the `Layout` extension: +It consists two major steps to integrate the Enhanced Readabilities plugin into your VitePress project: + +1. [Add plugin-specific options into configurations of Vite](#add-plugin-specific-options-into-configurations-of-vite) +2. [Add plugin into the Theme options of VitePress](#add-plugin-into-the-theme-options-of-vitepress) + +#### 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 Blinking highlight targeted heading plugin package name `@nolebase/vitepress-plugin-highlight-targeted-heading` into the Vite options that required by VitePress to process this plugin: + + + +```typescript +import { defineConfig } from 'vitepress' + +// https://vitepress.dev/reference/site-config +export default defineConfig({ + vite: { // [!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-highlight-targeted-heading', // [!code ++] + ], // [!code ++] + }, // [!code ++] + }, // [!code ++] + themeConfig: { + lang: 'en', + title: 'Site Name', + // 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: + + + +```typescript +import { defineConfig } from 'vite' + +export default defineConfig(() => { + return { + 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-highlight-targeted-heading', // [!code ++] + ], // [!code ++] + }, // [!code ++] + optimizeDeps: { + exclude: ['vitepress'], + }, + 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!) + +#### Add plugin into the Theme options of VitePress + +In VitePress's [**theme configuration file**](https://vitepress.dev/reference/default-theme-config#default-theme-config) (note that it's not a **configuration file**, it's usually located at `docs/.vitepress/theme/index.ts`, file paths and extensions may be vary), import `@nolebase/vitepress-plugin-highlight-targeted-heading` import and add it to the `Layout` extension: diff --git a/docs/pages/zh-CN/integrations/vitepress-plugin-highlight-targeted-heading/index.md b/docs/pages/zh-CN/integrations/vitepress-plugin-highlight-targeted-heading/index.md index 2df5e114..4690da3b 100644 --- a/docs/pages/zh-CN/integrations/vitepress-plugin-highlight-targeted-heading/index.md +++ b/docs/pages/zh-CN/integrations/vitepress-plugin-highlight-targeted-heading/index.md @@ -63,6 +63,72 @@ yarn add @nolebase/vitepress-plugin-highlight-targeted-heading ### 为 VitePress 配置 +配置分为两个大步骤： + +1. [添加 Vite 相关的配置](#添加-vite-相关的配置) +2. [添加 VitePress 主题相关的配置](#添加-vitepress-主题相关的配置) + +#### 添加 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-highlight-targeted-heading` 添加到需要 VitePress 底层的 Vite 帮忙处理的依赖： + + + +```typescript +import { defineConfig } from 'vitepress' + +// https://vitepress.dev/reference/site-config +export default defineConfig({ + vite: { // [!code ++] + ssr: { // [!code ++] + noExternal: [ // [!code ++] + // 如果还有别的依赖需要添加的话，并排填写和配置到这里即可 // [!code hl] + '@nolebase/vitepress-plugin-highlight-targeted-heading', // [!code ++] + ], // [!code ++] + }, // [!code ++] + }, // [!code ++] + themeConfig: { + lang: 'zh-CN', + title: '网站标题', + // 其他的配置... + } + // 其他的配置... +}) +``` + +如果你很厉害，为 VitePress 的文档站点配置了分离和单独的 [Vite 配置文件](https://vitejs.dev/config/)（比如 `vite.config.ts`），那你也可以省略上面的配置，直接在 Vite 的配置文件中添加下面的配置： + + + +```typescript +import { defineConfig } from 'vite' + +export default defineConfig(() => { + return { + ssr: { // [!code ++] + noExternal: [ // [!code ++] + // 如果还有别的依赖需要添加的话，并排填写和配置到这里即可 // [!code hl] + '@nolebase/vitepress-plugin-highlight-targeted-heading', // [!code ++] + ], // [!code ++] + }, // [!code ++] + optimizeDeps: { + exclude: ['vitepress'], + }, + 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`，文件路径和拓展名也许会有区别），将 `@nolebase/vitepress-plugin-highlight-targeted-heading` 导入，并且将其添加到 `Layout` 的拓展中： diff --git a/packages/vitepress-plugin-highlight-targeted-heading/src/components/HighlightTargetedHeading.vue b/packages/vitepress-plugin-highlight-targeted-heading/src/components/HighlightTargetedHeading.vue index 7062c27b..676275d8 100644 --- a/packages/vitepress-plugin-highlight-targeted-heading/src/components/HighlightTargetedHeading.vue +++ b/packages/vitepress-plugin-highlight-targeted-heading/src/components/HighlightTargetedHeading.vue @@ -1,6 +1,7 @@ diff --git a/packages/vitepress-plugin-highlight-targeted-heading/vite.config.ts b/packages/vitepress-plugin-highlight-targeted-heading/vite.config.ts index f8f6eeab..879c659a 100644 --- a/packages/vitepress-plugin-highlight-targeted-heading/vite.config.ts +++ b/packages/vitepress-plugin-highlight-targeted-heading/vite.config.ts @@ -5,6 +5,7 @@ export default defineConfig({ resolve: { dedupe: [ 'vue', + 'vitepress', '@vue/runtime-core', ], }, @@ -20,10 +21,12 @@ export default defineConfig({ rollupOptions: { external: [ 'vue', + 'vitepress', ], output: { globals: { vue: 'Vue', + vitepress: 'vitepress', }, }, }, From 35e5bd98f53f9383913fe5f75f94a5dbaf8b362b Mon Sep 17 00:00:00 2001 From: Neko Ayaka Date: Tue, 12 Dec 2023 21:30:40 +0800 Subject: [PATCH 2/3] docs: update docs Signed-off-by: Neko Ayaka --- .../vitepress-plugin-highlight-targeted-heading/index.md | 5 +++++ .../vitepress-plugin-highlight-targeted-heading/index.md | 5 +++++ 2 files changed, 10 insertions(+) diff --git a/docs/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/index.md b/docs/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/index.md index 7be0fe1b..d70c3931 100644 --- a/docs/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/index.md +++ b/docs/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/index.md @@ -2,6 +2,11 @@ ## Demo +Try clicking the following two links and observe the changes of the title elements: + +- [Highlight headings across pages](pages/en/guide/getting-started.html#getting-started) +- [Highlight headings within the page](#how-to-use) + diff --git a/docs/pages/zh-CN/integrations/vitepress-plugin-highlight-targeted-heading/index.md b/docs/pages/zh-CN/integrations/vitepress-plugin-highlight-targeted-heading/index.md index 4690da3b..f89c5510 100644 --- a/docs/pages/zh-CN/integrations/vitepress-plugin-highlight-targeted-heading/index.md +++ b/docs/pages/zh-CN/integrations/vitepress-plugin-highlight-targeted-heading/index.md @@ -2,6 +2,11 @@ ## 效果演示 +可以试着点击下面的两个链接，然后观察标题部分发生的变化： + +- [跨页面高亮目标标题](pages/zh-CN/guide/getting-started.html#getting-started) +- [页面内高亮目标标题](#如何使用) + From d26347a343cc765f2b3f48b79f22541206df25e9 Mon Sep 17 00:00:00 2001 From: Neko Ayaka Date: Tue, 12 Dec 2023 21:36:27 +0800 Subject: [PATCH 3/3] docs: update docs Signed-off-by: Neko Ayaka --- .../vitepress-plugin-highlight-targeted-heading/index.md | 2 +- .../vitepress-plugin-highlight-targeted-heading/index.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/index.md b/docs/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/index.md index d70c3931..d44fe344 100644 --- a/docs/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/index.md +++ b/docs/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/index.md @@ -4,7 +4,7 @@ Try clicking the following two links and observe the changes of the title elements: -- [Highlight headings across pages](pages/en/guide/getting-started.html#getting-started) +- [Highlight headings across pages](/pages/en/guide/getting-started.html#getting-started) - [Highlight headings within the page](#how-to-use)