资源处理
引用静态资源
所有Markdown文件都会编译成Vue组件并由Vite处理。您可以,并且应该,使用相对 URL 引用任何资源:
![An image](./image.png)
您可以使用绝对公共路径(基于项目根)或相对路径(基于您的文件系统)在 Markdown 文件中引用静态资源、主题中的*.vue
组件、样式和纯.css
文件。后者类似于您使用过 Vite、Vue CLI 或 webpack 的"文件加载器"时所习惯的行为。
自动检测常见图像、媒体和字体文件类型并将其包含为资源。
所有引用的资源(包括使用绝对路径的资源)都将在生产版本中以哈希文件名复制到输出目录。从未引用的资源将不会被复制。小于 4kb 的图像资源将采用 base64 内联 - 这可以通过 vite
配置选项进行配置。
所有静态路径引用,包括绝对路径,都应基于您的工作目录结构。
公共目录
有时,您可能需要提供在任何 Markdown 或主题组件中未直接引用的静态资源,或者您可能希望使用原始文件名提供某些文件。此类文件的示例包括robots.txt
、favicons 和 PWA 图标。
您可以将这些文件放在源目录下的public
目录中。例如,如果您的项目根目录是./docs
并使用默认源目录位置,那么您的公共目录将为./docs/public
。
放置在public
中的资源将按原样复制到输出目录的根目录。
请注意,您应该使用根绝对路径引用放置在public
中的文件 - 例如,public/icon.png
应始终在源代码中引用为/icon.png
。
有一个例外:如果您在public
中有一个 HTML 页面并从主站点链接到该页面,则默认情况下路由器将生成 404。为了解决这个问题,VitePress 提供了一个 pathname://
协议,它允许您链接到同一域中的另一个页面,就像链接是外部的一样。比较这两个链接:
Note that pathname://
is only supported in Markdown links. Also, pathname://
will open the link in a new tab by default. You can use target="_self"
instead to open it in the same tab:
输入
[Link to pure.html](/pure.html){target="_self"}
<!-- there is no need to specify pathname:// if the target is explicitly specified -->
输出
基本网址
如果您的站点部署到非根 URL,则需要在.vitepress/config.js
中设置base
选项。例如,如果您计划将站点部署到https://foo.github.io/bar/
,则base
应设置为'/bar/'
(它应始终以削减)。
所有静态资源路径都会自动处理,以适应不同的base
配置值。例如,如果您在 markdown 中对public
下的资源有绝对引用:
![An image](/image-inside-public.png)
在这种情况下,当您更改base
配置值时,您不需要需要更新它。
但是,如果您正在编写动态链接到资源的主题组件,例如src
基于主题配置值的图像:
<img :src="theme.logoPath" />
在这种情况下,建议使用 VitePress 提供的 withBase
helper 包裹路径:
<script setup>
import { withBase, useData } from 'vitepress'
const { theme } = useData()
</script>
<template>
<img :src="withBase(theme.logoPath)" />
</template>