From 0fe98a38f1ed6f5538aa8bc00bb141f4b5d07d72 Mon Sep 17 00:00:00 2001 From: pengzhanbo Date: Thu, 10 Jul 2025 11:23:05 +0800 Subject: [PATCH] feat(theme): migrate to `@vuepress/plugin-replace-assets` (#644) --- CONTRIBUTING.en-US.md | 1 - CONTRIBUTING.md | 1 - .../theme/guide/features/replace-assets.md | 72 +++++- plugins/plugin-replace-assets/LICENSE | 21 -- .../__snapshots__/transform.spec.ts.snap | 51 ---- .../__test__/normalizeRules.spec.ts | 131 ----------- .../__test__/transform.spec.ts | 218 ------------------ .../__test__/unplugin-utils.spec.ts | 25 -- plugins/plugin-replace-assets/package.json | 50 ---- .../plugin-replace-assets/src/constants.ts | 31 --- plugins/plugin-replace-assets/src/index.ts | 4 - .../src/normalizeRules.ts | 56 ----- plugins/plugin-replace-assets/src/options.ts | 19 -- plugins/plugin-replace-assets/src/plugin.ts | 40 ---- .../src/unplugin/factory.ts | 18 -- .../src/unplugin/index.ts | 17 -- .../src/unplugin/transform.ts | 69 ------ .../src/unplugin/utils.ts | 26 --- .../plugin-replace-assets/tsdown.config.ts | 23 -- pnpm-lock.yaml | 44 ++-- pnpm-workspace.yaml | 3 +- theme/package.json | 4 +- theme/src/node/plugins/setupPlugins.ts | 2 +- theme/src/shared/options.ts | 2 +- theme/src/shared/plugins.ts | 2 +- 25 files changed, 86 insertions(+), 844 deletions(-) delete mode 100644 plugins/plugin-replace-assets/LICENSE delete mode 100644 plugins/plugin-replace-assets/__test__/__snapshots__/transform.spec.ts.snap delete mode 100644 plugins/plugin-replace-assets/__test__/normalizeRules.spec.ts delete mode 100644 plugins/plugin-replace-assets/__test__/transform.spec.ts delete mode 100644 plugins/plugin-replace-assets/__test__/unplugin-utils.spec.ts delete mode 100644 plugins/plugin-replace-assets/package.json delete mode 100644 plugins/plugin-replace-assets/src/constants.ts delete mode 100644 plugins/plugin-replace-assets/src/index.ts delete mode 100644 plugins/plugin-replace-assets/src/normalizeRules.ts delete mode 100644 plugins/plugin-replace-assets/src/options.ts delete mode 100644 plugins/plugin-replace-assets/src/plugin.ts delete mode 100644 plugins/plugin-replace-assets/src/unplugin/factory.ts delete mode 100644 plugins/plugin-replace-assets/src/unplugin/index.ts delete mode 100644 plugins/plugin-replace-assets/src/unplugin/transform.ts delete mode 100644 plugins/plugin-replace-assets/src/unplugin/utils.ts delete mode 100644 plugins/plugin-replace-assets/tsdown.config.ts diff --git a/CONTRIBUTING.en-US.md b/CONTRIBUTING.en-US.md index 3bbbad97..a4532653 100644 --- a/CONTRIBUTING.en-US.md +++ b/CONTRIBUTING.en-US.md @@ -13,7 +13,6 @@ In the `plugins` directory: - `plugin-search`: Provides full-text fuzzy search functionality for the theme. - `plugin-md-power`: Provides enhanced markdown features. -- `plugin-replace-assets`: Provides resource link replacement functionality - `plugin-fonts`: Provides special character font support ## Development Configuration diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b456c112..35135b23 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -13,7 +13,6 @@ - `plugin-search`: 为主题提供 全文模糊搜索 功能 - `plugin-md-power`: 提供 markdown 增强功能 -- `plugin-replace-assets`: 提供资源链接替换功能 - `plugin-fonts`: 提供特殊字符字体支持 ## 开发配置 diff --git a/docs/notes/theme/guide/features/replace-assets.md b/docs/notes/theme/guide/features/replace-assets.md index 9f26e109..0d85e924 100644 --- a/docs/notes/theme/guide/features/replace-assets.md +++ b/docs/notes/theme/guide/features/replace-assets.md @@ -8,11 +8,12 @@ badge: 新 ## 概述 -此功能由 [vuepress-plugin-replace-assets](https://github.com/pengzhanbo/vuepress-theme-plume/tree/main/plugins/plugin-replace-assets) 插件提供。 +此功能由 [@vuepress/plugin-replace-assets](https://ecosystem.vuejs.press/zh/plugins/tools/replace-assets.html) 插件提供。 替换站点内的本地资源链接，比如 图片、视频、音频、PDF 等资源的链接地址，将本地资源地址改写到新的地址。 -::: tip 为什么需要这个功能？ +## 为什么需要这个功能？ + 不少用户会选择将站点的资源存放到 CDN 服务上，从而加速站点的访问速度，提升站点的可用性。 在这个过程中，通常需要先将资源上传到 CDN 服务，然后再获取 CDN 服务的资源链接，最后才在站点内容中使用。 @@ -26,10 +27,6 @@ badge: 新 在此过程中，内容创作被频繁的打断。 此功能旨在解决这个问题。在内容创作过程中，只需要直接使用本地资源地址，由主题内部在合适的阶段，完成资源地址的替换。 -::: - -::: important 此功能仅查找 `/` 开头的本地静态资源链接，比如 `/images/foo.jpg` -::: ::: important 此功能不会修改源文件，仅在编译后的内容中进行替换 ::: @@ -67,6 +64,56 @@ export default defineUserConfig({ }) ``` +### 资源管理 + +**你应该将资源存放在 [.vuepress/public](https://v2.vuepress.vuejs.org/zh/guide/assets.html#public-%E6%96%87%E4%BB%B6) 目录下**: + +```sh +./docs +├── .vuepress +│ └── public # [!code hl:6] +│ ├── images +│ │ ├── foo.jpg +│ │ └── bar.jpg +│ └── medias +│ └── foo.mp4 +└── README.md +``` + +::: tip 为什么需要存放在这个目录下？ +当站点完成编译准备部署前，我们可以很方便地直接将这个目录下的文件上传到 CDN 。 +::: + +在 markdown 中，直接使用本地资源地址： + +```md +![foo](/images/foo.jpg) + + +``` + +在 `javascript` 中： + +```js +const foo = '/images/foo.jpg' + +const img = document.createElement('img') +img.src = '/images/foo.jpg' +``` + +以及在 样式文件 中： + +```css +.foo { + background: url('/images/foo.jpg'); +} +``` + +插件会正确识别这些资源，并在编译后的内容中进行替换。 + +:::warning 插件不支持识别 `'/images/' + 'foo.jpg'` 拼接的路径。 +::: + ## 配置说明 ```ts @@ -120,11 +167,11 @@ interface ReplaceAssetsOptions { 为便于使用，主题插件内部提供了内置的资源匹配规则，你可以直接使用它们。 -- `image`: 查找图片资源，包括 `['jpg', 'jpeg', 'png', 'gif', 'svg', 'webp', 'avif']` 格式的本地图片资源链接 -- `media`: 查找媒体资源，包括 `['mp4', 'webm', 'ogg', 'mp3', 'wav', 'flac', 'aac', 'm3u8', 'm3u', 'flv', 'pdf']` 格式的本地媒体资源链接 +- `image`: 查找图片资源，包括 `['apng','bmp','png','jpeg','jpg','jfif','pjpeg','pjp','gif','svg','ico','webp','avif','cur','jxl']` 格式的本地图片资源链接 +- `media`: 查找媒体资源，包括 `['mp4','webm','ogg','mp3','wav','flac','aac','opus','mov','m4a','vtt','pdf']` 格式的本地媒体资源链接 - `all`: 查找 图片 和 媒体资源，即 `image` 和 `media` 的合集 -直接传入 __资源链接前缀__ 或 __资源链接替换函数__ 时，主题使用 `all` 规则替换资源链接。 +直接传入 **资源链接前缀** 或 **资源链接替换函数** 时，主题使用 `all` 规则替换资源链接。 ```ts title=".vuepress/config.ts" import process from 'node:process' @@ -204,11 +251,11 @@ export default defineUserConfig({ }) ``` -__`find` 字段说明__ +**`find` 字段说明** -`find` 字段用于匹配资源链接，可以是一个 __正则表达式__ 或 __字符串__。 +`find` 字段用于匹配资源链接，可以是一个 **正则表达式** 或 **字符串**。 -当传入的是一个 `字符串` 时，如果是以 `^` 开头或者以 `$` 结尾的字符串，则会自动转换为一个 __正则表达式__。 +当传入的是一个 `字符串` 时，如果是以 `^` 开头或者以 `$` 结尾的字符串，则会自动转换为一个 **正则表达式**。 否则则会检查资源链接是否 以 `find` 结尾 或者 以 `find` 开头。 ```txt @@ -217,3 +264,4 @@ __`find` 字段说明__ ``` ::: important 所有匹配的资源地址都是以 `/` 开头。 +::: diff --git a/plugins/plugin-replace-assets/LICENSE b/plugins/plugin-replace-assets/LICENSE deleted file mode 100644 index 9f677c90..00000000 --- a/plugins/plugin-replace-assets/LICENSE +++ /dev/null @@ -1,21 +0,0 @@ -The MIT License (MIT) - -Copyright (C) 2021 - PRESENT by pengzhanbo - -Permission is hereby granted, free of charge, to any person obtaining a copy -of this software and associated documentation files (the "Software"), to deal -in the Software without restriction, including without limitation the rights -to use, copy, modify, merge, publish, distribute, sublicense, and/or sell -copies of the Software, and to permit persons to whom the Software is -furnished to do so, subject to the following conditions: - -The above copyright notice and this permission notice shall be included in -all copies or substantial portions of the Software. - -THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR -IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, -FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE -AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER -LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, -OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN -THE SOFTWARE. diff --git a/plugins/plugin-replace-assets/__test__/__snapshots__/transform.spec.ts.snap b/plugins/plugin-replace-assets/__test__/__snapshots__/transform.spec.ts.snap deleted file mode 100644 index 3cbca0a7..00000000 --- a/plugins/plugin-replace-assets/__test__/__snapshots__/transform.spec.ts.snap +++ /dev/null @@ -1,51 +0,0 @@ -// Vitest Snapshot v1, https://vitest.dev/guide/snapshot.html - -exports[`plugin-replace-assets > transformAssets > should work with like css 1`] = ` -".foo { - background-image: url("https://example.com/assets/images/foo.jpg"); - background-image: url("https://example.com/assets/images/foo.png"); - background-image: url("https://example.com/assets/images/foo.gif"); - background-image: url("https://example.com/assets/images/foo.svg"); - background-image: url("https://example.com/assets/medias/foo.mp4"); - - background-image: url("https://example.com/assets/images/foo.jpg"); - background-image: url("https://example.com/assets/images/foo.png"); - - background-image: url("https://example.com/assets/images/foo.jpg?a=1"); - - background-image: url("https://not-replace.com/images/foo.jpg"); - - background: url("https://example.com/assets/images/foo.png"); - -} -" -`; - -exports[`plugin-replace-assets > transformAssets > should work with like html 1`] = ` -" - - - - - - - - - - -