VitePress 安装与配置教程：轻松搭建现代文档网站

软考鸭

已于 2024-09-05 09:01:47 修改

阅读量715

点赞数 6

分类专栏： vitepress 文章标签： vitepress

于 2024-09-05 09:01:35 首次发布

本文链接：https://blog.csdn.net/gusushantang/article/details/141918199

版权

vitepress 专栏收录该内容

17 篇文章 1 订阅

订阅专栏

VitePress 是一个基于 Vite 和 Vue 3 的静态网站生成器，特别适用于构建文档网站。它提供了快速的开发体验、即时热更新以及优秀的性能。本文将详细介绍如何安装和配置 VitePress，并通过实例代码帮助你快速上手。

一、安装前准备

在开始之前，请确保你已经安装了以下工具：

Node.js 版本 18 或更高。
终端用于访问 VitePress 的命令行界面（CLI）。
文本编辑器 支持 Markdown 语法，推荐使用 VSCode，并安装官方 Vue 扩展。

二、安装 VitePress

VitePress 可以单独使用，也可以安装到现有项目中。无论哪种情况，你都可以通过以下包管理工具进行安装：

使用 npm:

$ npm add -D vitepress

使用 pnpm:

$ pnpm add -D vitepress

使用 yarn:

$ yarn add -D vitepress

使用 bun:

$ bun add -D vitepress

注意：VitePress 是一个 ESM（ECMAScript Module）包，不要使用 require() 来导入它。确保你的 package.json 中包含 "type": "module"，或者将相关文件的扩展名更改为 .mjs 或 .mts。

三、初始化项目

VitePress 提供了一个命令行设置向导，帮助你快速搭建基本项目。安装完成后，运行以下命令启动向导：

使用 npm:

$ npx vitepress init

使用 pnpm:

$ pnpm vitepress init

使用 yarn:

$ yarn vitepress init

使用 bun:

$ bun vitepress init

向导会询问你几个问题，例如配置文件的位置、网站标题、描述以及主题选择。根据你的需求进行选择即可。

四、项目结构

假设你选择将 VitePress 项目架构在 ./docs 目录下，生成的文件结构应如下所示：

.
├─ docs
│  ├─ .vitepress
│  │  └─ config.js
│  ├─ api-examples.md
│  ├─ markdown-examples.md
│  └─ index.md
└─ package.json

docs 目录是 VitePress 站点的项目根目录，.vitepress 目录包含配置文件、开发服务器缓存、构建输出以及可选的主题定制代码。

五、配置文件

配置文件 .vitepress/config.js 允许你自定义 VitePress 站点的各个方面。最基本的配置选项包括站点的标题和描述：

// .vitepress/config.js
export default {
  title: 'VitePress',
  description: 'Just playing around.',
  themeConfig: {
    // 主题级选项
  }
}

你可以在 themeConfig 选项中配置主题的特定行为。有关所有配置选项的详细信息，请参阅配置引用。

六、源文件

.vitepress 目录之外的 Markdown 文件被视为源文件。VitePress 使用基于文件的路由：每个 .md 文件都会被编译成具有相同路径的相应 .html 文件。例如，index.md 将被编译为 index.html，并可以通过 VitePress 站点的根路径 / 访问。

七、启动开发服务器

如果允许设置向导修改你的 package.json，它会注入以下 npm 脚本：

{
  ...
  "scripts": {
    "docs:dev": "vitepress dev docs",
    "docs:build": "vitepress build docs",
    "docs:preview": "vitepress preview docs"
  },
  ...
}