diff --git a/docs/.vuepress/configs/sidebar/en.ts b/docs/.vuepress/configs/sidebar/en.ts index 36a6c27048..09d4530e00 100644 --- a/docs/.vuepress/configs/sidebar/en.ts +++ b/docs/.vuepress/configs/sidebar/en.ts @@ -159,6 +159,7 @@ export const sidebarEn: SidebarOptions = { 'google-tag-manager', 'redirect', 'register-components', + 'replace-assets', ], '/plugins/search/': [ diff --git a/docs/.vuepress/configs/sidebar/zh.ts b/docs/.vuepress/configs/sidebar/zh.ts index 31b0273f41..e44d2b576b 100644 --- a/docs/.vuepress/configs/sidebar/zh.ts +++ b/docs/.vuepress/configs/sidebar/zh.ts @@ -159,6 +159,7 @@ export const sidebarZh: SidebarOptions = { 'google-tag-manager', 'redirect', 'register-components', + 'replace-assets', ], '/zh/plugins/search/': [ diff --git a/docs/plugins/tools/replace-assets.md b/docs/plugins/tools/replace-assets.md new file mode 100644 index 0000000000..a3a07413c5 --- /dev/null +++ b/docs/plugins/tools/replace-assets.md @@ -0,0 +1,272 @@ +--- +icon: lucide:replace +--- + +# replace-assets + + + +Replace local assets links within the site, such as links to images, videos, audio, PDF, and other assets, by rewriting the local assets addresses to new ones. + +## Why is this feature needed? {#why-need-this} + +Many users choose to store their site's assets on CDN services to accelerate site access speed and improve site availability. + +In this process, it is usually necessary to first upload the assets to the CDN service, then obtain the asset links from the CDN service, and finally use them in the site content. + +This may seem fine at first glance, but in actual usage, it often requires repeatedly performing the following steps: + +```txt +Upload assets -> Obtain asset links -> Use full asset links in content +``` + +During this process, content creation is frequently interrupted. + +This plugin aims to solve this problem. During content creation, you only need to directly use local asset addresses, and the plugin will handle the replacement of asset addresses at the appropriate stage. + +::: important The plugin does not modify the source files; it only performs replacements in the compiled content. +::: + +## Usage + +### Install + +```sh +npm i -D @vuepress/plugin-replace-assets@next +``` + +### Configuration + +```ts title=".vuepress/config.ts" +import { replaceAssetsPlugin } from '@vuepress/plugin-replace-assets' + +export default { + plugins: [ + replaceAssetsPlugin('https://cnd.example.com'), // ReplaceAssetsPluginOptions + ], +} +``` + +### Assets Management + +**You should store the assets in the [.vuepress/public](https://v2.vuepress.vuejs.org/guide/assets.html#public-files) directory**: + +```sh +./docs +├── .vuepress +│ └── public # [!code hl:6] +│ ├── images +│ │ ├── foo.jpg +│ │ └── bar.jpg +│ └── medias +│ └── foo.mp4 +└── README.md +``` + +::: tip Why is it necessary to store files in this directory? + +Before the site is compiled and ready for deployment, we can easily upload the files from this directory directly to a CDN. + +::: + +In markdown, use local resource paths directly: + +```md +![foo](/images/foo.jpg) + + +``` + +In `javascript`: + +```js +const foo = '/images/foo.jpg' + +const img = document.createElement('img') +img.src = '/images/foo.jpg' +``` + +In `css`: + +```css +.foo { + background: url('/images/foo.jpg'); +} +``` + +The plugin will correctly identify these resources and replace them in the compiled content. + +:::warning The plugin does not support recognizing concatenated paths like `'/images/' + 'foo.jpg'`. + +::: + +## Options + +```ts +/** + * Assets Replacement Target Path + * - `string`: Directly concatenated before the original path + * - `(url) => string`: Custom replacement method, returns the new path + */ +export type Replacement = string | ((url: string) => string) + +/** + * Assets Replacement Rule + */ +export interface ReplacementRule { + /** + * Assets Matching + * + * - `RegExp`: Match using regular expression + * - `string`: Match using string + * - Strings starting with `^` or ending with `$` are automatically converted to regular expressions + * - For ordinary strings, checks if they appear at the start or end + */ + find: RegExp | string + + /** + * Assets Replacement Target Path + */ + replacement: Replacement +} + +export interface ReplaceAssetsOptions { + /** + * Custom Assets Replacement Rules + */ + rules?: ReplacementRule | ReplacementRule[] + /** + * Built-in image matching rules, designed to match and find common image paths starting with `^/images/` + */ + image?: Replacement + /** + * Built-in media matching rules, designed to match and locate common media paths such as videos and audio that start with `^/medias/`. + */ + media?: Replacement + /** + * Equivalent to setting both `image` and `media` simultaneously. + */ + all?: Replacement +} + +/** + * Assets Replacement Plugin Options + */ +export type ReplaceAssetsPluginOptions = + | ReplaceAssetsOptions + | Replacement + | ReplacementRule + | ReplacementRule[] +``` + +### Built-in Asset Matching Rules + +For ease of use, the plugin provides built-in assets matching rules that you can directly utilize. + +- `image`: Find image assets in the `.vuepress/public/images` directory, including local image asset links in formats such as `['apng','bmp','png','jpg','jpeg','jfif','pjpeg','pjp','gif','svg','ico','webp','avif','cur','jxl']`: + + ```md + ![](/images/foo.jpg) + + ``` + +- `media`: Find media assets in the `.vuepress/public/medias` directory, including local media asset links in formats such as `['mp4','webm','ogg','mp3','wav','flac','aac','opus','mov','m4a','vtt','pdf']`: + + ```md +