VitePress的官方描述是:由 Vite 和 Vue 驱动的静态站点生成器将 Markdown 变成优雅的文档,只需几分钟!
VitePress 是一个基于 Vite 的静态网站生成器,专门用于文档和博客的构建。它使用 Vue 3 和 Markdown 来创建快速、可定制的文档网站。VitePress 由 Vue.js 核心团队开发,提供了一种简单而高效的方式来创建和维护文档。
主要特点
-
快速构建:利用 Vite 的快速构建和热更新能力,提供即时反馈和开发体验。
-
Markdown 支持:VitePress 使用 Markdown 来编写文档,支持标准 Markdown 语法以及一些扩展功能,如自定义容器、插入代码块等。
-
主题系统:提供默认主题,可以通过配置或自定义主题来满足不同的需求。
-
路由管理:自动生成基于文件结构的路由,简化文档页面的管理。
-
嵌套结构:支持文档的多层嵌套结构,便于组织和分类内容。
-
代码高亮:内置 Prism.js 提供代码高亮,支持多种语言和主题。
-
PWA 支持:可以通过插件轻松集成 PWA(渐进式 Web 应用)。
-
自定义组件:可以在 Markdown 中使用 Vue 组件,增强文档的交互性。
安装
要安装 VitePress,您可以通过 npm 或 yarn 进行安装。以下是基本的安装步骤:
-
创建项目目录:
mkdir my-docs cd my-docs
-
初始化项目:
npm init -y
-
安装 VitePress:
npm install vitepress --save-dev
基本用法
1. 项目结构
创建以下项目结构:
my-docs
├── docs
│ ├── .vitepress
│ │ └── config.js
│ ├── index.md
│ └── guide.md
└── package.json
2. 配置文件
在 .vitepress/config.js
中添加基本配置:
module.exports = {
title: 'My Documentation',
description: 'A simple documentation site using VitePress',
themeConfig: {
nav: [
{ text: 'Home', link: '/' },
{ text: 'Guide', link: '/guide' },
],
sidebar: [
{ text: 'Home', link: '/' },
{ text: 'Guide', link: '/guide' },
],
},
}
3. 编写 Markdown 文件
在 index.md
中编写内容:
# Welcome to My Documentation
This is the homepage of my documentation site.
## Getting Started
To get started, check out the [Guide](/guide).
在 guide.md
中编写内容:
# Guide
This is the guide section of the documentation.
4. 启动开发服务器
在 package.json
中添加启动脚本:
{
"scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs"
}
}
然后运行:
npm run docs:dev
这将启动开发服务器,您可以在浏览器中访问 http://localhost:3000
。
构建和部署
在完成文档的编写后,可以使用以下命令构建静态文件:
npm run docs:build
构建完成后,生成的静态文件将位于 docs/.vitepress/dist
目录中,您可以将其部署到任何静态网站托管服务(如 GitHub Pages、Vercel、Netlify 等)。
示例项目
您可以查看 VitePress 的 官方示例 以获取更多的使用示例和配置选项。
总结
VitePress 是一个快速、灵活的静态网站生成器,适合用来创建文档和博客。它基于 Vite 的技术栈,能够提供出色的开发体验和性能。通过 Markdown 编写文档和自定义主题,用户可以轻松创建和维护一个现代化的文档网站。