mirror of https://github.com/vuejs/vitepress
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
83 lines
4.0 KiB
83 lines
4.0 KiB
---
|
|
description: Learn how to reference and handle static assets such as images, media, and fonts in VitePress.
|
|
---
|
|
|
|
# Asset Handling
|
|
|
|
## Referencing Static Assets
|
|
|
|
All Markdown files are compiled into Vue components and processed by [Vite](https://vite.dev/guide/assets.html). You can, **and should**, reference any assets using relative URLs:
|
|
|
|
```md
|
|
|
|
```
|
|
|
|
You can reference static assets in your markdown files, your `*.vue` components in the theme, styles and plain `.css` files either using absolute public paths (based on project root) or relative paths (based on your file system). The latter is similar to the behavior you are used to if you have used Vite, Vue CLI, or webpack's `file-loader`.
|
|
|
|
Common image, media, and font filetypes are detected and included as assets automatically.
|
|
|
|
::: tip Linked files are not treated as assets
|
|
PDFs or other documents referenced by links within markdown files are not automatically treated as assets. To make linked files accessible, you must manually place them within the [`public`](#the-public-directory) directory of your project.
|
|
:::
|
|
|
|
All referenced assets, including those using absolute paths, will be copied to the output directory with a hashed file name in the production build. Never-referenced assets will not be copied. Image assets smaller than 4kb will be base64 inlined - this can be configured via the [`vite`](../reference/site-config#vite) config option.
|
|
|
|
All **static** path references, including absolute paths, should be based on your working directory structure.
|
|
|
|
## The Public Directory
|
|
|
|
Sometimes you may need to provide static assets that are not directly referenced in any of your Markdown or theme components, or you may want to serve certain files with the original filename. Examples of such files include `robots.txt`, favicons, and PWA icons.
|
|
|
|
You can place these files in the `public` directory under the [source directory](./routing#source-directory). For example, if your project root is `./docs` and using default source directory location, then your public directory will be `./docs/public`.
|
|
|
|
Assets placed in `public` will be copied to the root of the output directory as-is.
|
|
|
|
Note that you should reference files placed in `public` using root absolute path - for example, `public/icon.png` should always be referenced in source code as `/icon.png`.
|
|
|
|
## Base URL
|
|
|
|
If your site is deployed to a non-root URL, set the [`base`](../reference/site-config#base) option. For example, if you plan to deploy your site to `https://foo.github.io/bar/`, then `base` should be set to `'/bar/'`
|
|
|
|
Static asset references are automatically adjusted for the base, so an absolute reference to a file in `public` works with any `base` and never needs updating:
|
|
|
|
```md
|
|
|
|
```
|
|
|
|
Only dynamically constructed paths need care — for example, an image whose `src` is based on a theme config value. Wrap those with the [`withBase` helper](../reference/runtime-api#withbase) so the base is prepended at runtime:
|
|
|
|
```vue
|
|
<script setup>
|
|
import { withBase, useData } from 'vitepress'
|
|
|
|
const { theme } = useData()
|
|
</script>
|
|
|
|
<template>
|
|
<img :src="withBase(theme.logoPath)" />
|
|
</template>
|
|
```
|
|
|
|
## Serving Assets from a CDN
|
|
|
|
To serve the generated assets — scripts, styles, fonts, and images imported from Markdown or components — from a different origin than the pages, set [`assetsBase`](../reference/site-config#assetsbase):
|
|
|
|
```ts
|
|
export default {
|
|
base: '/',
|
|
assetsBase: 'https://cdn.example.com/'
|
|
}
|
|
```
|
|
|
|
Upload the `assets` directory from the build output to the CDN so it is reachable at `https://cdn.example.com/assets/`, and deploy the rest of the output to your site as usual. Files in `public` are referenced from `base` and stay with the pages.
|
|
|
|
Since the value is often environment-specific, it can also be passed on the command line:
|
|
|
|
```sh
|
|
vitepress build docs --assetsBase "$CDN_URL"
|
|
```
|
|
|
|
::: warning CORS Required
|
|
Module scripts are always fetched in CORS mode, so a cross-origin CDN must respond with an appropriate `Access-Control-Allow-Origin` header.
|
|
:::
|