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?
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:
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.
The plugin does not modify the source files; it only performs replacements in the compiled content.
Usage
Install
npm i -D @vuepress/plugin-replace-assets@next
Configuration
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 directory:
./docs
├── .vuepress
│ └── public
│ ├── images
│ │ ├── foo.jpg
│ │ └── bar.jpg
│ └── medias
│ └── foo.mp4
└── README.md
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:

<img src="/images/foo.jpg">
In javascript
:
const foo = '/images/foo.jpg'
const img = document.createElement('img')
img.src = '/images/foo.jpg'
In css
:
.foo {
background: url('/images/foo.jpg');
}
The plugin will correctly identify these resources and replace them in the compiled content.
The plugin does not support recognizing concatenated paths like '/images/' + 'foo.jpg'
.
Options
/**
* 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']
: <img src="/images/bar/baz.png">
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']
:<video src="/medias/foo.mp4"> <audio src="/medias/bar.mp3">
all
: Locates both image and media assets, combining the rules ofimage
andmedia
.
When directly passing a asset link prefix or a asset link replacement function, the plugin uses the all
rule to replace asset links.
import { replaceAssetsPlugin } from '@vuepress/plugin-replace-assets'
export default {
plugins: [
// replaceAssetsPlugin('https://cnd.example.com')
replaceAssetsPlugin((url) => `https://cnd.example.com${url}`),
],
}
It is also possible to apply different asset link prefixes or asset link replacement functions for different built-in rules:
import { replaceAssetsPlugin } from '@vuepress/plugin-replace-assets'
export default {
plugins: [
// replaceAssetsPlugin({
// image: 'https://image.cdn.com',
// media: 'https://media.cdn.com'
// }),
replaceAssetsPlugin({
image: (url) => `https://image.cdn.com${url}`,
media: (url) => `https://media.cdn.com${url}`,
}),
],
}
Custom Asset Matching Rules
You can also customize asset matching rules:
import { replaceAssetsPlugin } from '@vuepress/plugin-replace-assets'
export default {
plugins: [
replaceAssetsPlugin({
find: /^\/images\/.*\.(jpg|jpeg|png|gif|svg|webp|avif)$/,
replacement: (url) => `https://image.cdn.com${url}`,
}),
],
}
You can also customize multiple matching rules:
import { replaceAssetsPlugin } from '@vuepress/plugin-replace-assets'
export default {
plugins: [
replaceAssetsPlugin([
// 查找图片资源
{
find: /^\/images\/.*\.(jpg|jpeg|png|gif|svg|webp|avif)$/,
replacement: 'https://image.cdn.com',
},
// 查找媒体资源
{
find: /^\/medias\/.*\.(mp4|webm|ogg|mp3|wav|flac|aac|m3u8|m3u|flv|pdf)$/,
replacement: (url) => `https://media.cdn.com${url}`,
},
]),
],
}
find
Field Description
The find
field is used to match asset links and can be either a regular expression or a string.
When the input is a string
:
- If it starts with
^
or ends with$
, it will automatically be converted into a regular expression. - Otherwise, it will check whether the asset link starts with
find
or ends withfind
.
'^/images/foo.jpg' -> /^\/images\/foo.jpg/
'/images/foo.jpg$' -> /^\/images\/foo.jpg$/
All matching asset paths start with /
.