Asset Handling

Referencing Static Assets

All Markdown files are compiled into Vue components and processed by Vite. You can, and should, reference any assets using relative URLs:

![An image](./image.png)

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.

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 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 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. 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 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:

![An image](/image-inside-public.png)

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 so the base is prepended at runtime:

<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:

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:

vitepress build docs --assetsBase "$CDN_URL"

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.