当今软件开发领域中，项目文档的重要性愈发凸显。好的文档不仅有助于团队协作，还能为用户提供明晰的指导。VitePress 是一个轻量级、快速的静态网站生成器，特别适用于构建项目文档。在这篇文章中，咱们将介绍如何快速运用 VitePress 构建你的项目文档。

VitePress 和 VuePress 相同，都是依据 vue 的静态站点生成器，可是 VitePress 采用了 vite 作为构建东西，比较 VuePress 依据 webpack 的构建东西，VitePress 的构建速度更快，同时也更轻量。

装置

预备条件

  • Node.js >= 18
  • markdown 编辑器

创立项目

首先咱们需求创立一个项目目录，然后在项目目录中获取 vitepress：

mkdir vitepress-demo
cd vitepress-demo
npm add -D vitepress

然后咱们能够经过官方提供的脚手架东西来创立项目：

npx vitepress init

依据你的状况挑选需求修改的部分：

┌  Welcome to VitePress!
│
◇  Where should VitePress initialize the config?
│  ./docs
│
◇  Site title:
│  My Awesome Project
│
◇  Site description:
│  A VitePress Site
│
◆  Theme:
│  ● Default Theme (Out of the box, good-looking docs)
│  ○ Default Theme   Customization
│  ○ Custom Theme
└

此时的项目结构如下：

.
├── docs # 文档目录，依据上面你自己填写的路径
│ ├── api-examples.md
│ ├── index.md
│ └── markdown-examples.md
├── node_modules
│ ├── ...
├── package.json
└── package-lock.json

发动项目

在项目目录下执行以下命令：

npm run docs:dev

当你看到以下输出时，说明项目发动成功：

  vitepress v1.0.0-rc.27
  ➜  Local:   http://localhost:5173/
  ➜  Network: use --host to expose
  ➜  press h to show help

此时你能够在浏览器中翻开 http://localhost:5173/ 检查项目。

项目装备

装备文件

VitePress 的装备文件是 .vitepress/config.mjs，咱们能够在这个文件中装备一些项目的基本信息，比方标题、描述、主题等。

// .vitepress/config.mjs
import { defineConfig } from 'vitepress'
// https://vitepress.dev/reference/site-config
export default defineConfig({
  title: "My Awesome Project", // 项目标题
  description: "A VitePress Site", // 项目描述
  themeConfig: {
    // 其他装备
  }
})

侧边栏

侧边栏是项目文档中最重要的部分，它能够协助用户快速定位到自己想要的内容。VitePress 的侧边栏装备十分简略，只需求在装备文件中增加 sidebar 字段即可。

// .vitepress/config.mjs
import { defineConfig } from 'vitepress'
// https://vitepress.dev/reference/site-config
export default defineConfig({
  themeConfig: {
    sidebar: [
      {
        text: 'Examples',
        items: [
          { text: 'Markdown Examples', link: '/markdown-examples' },
          { text: 'Runtime API Examples', link: '/api-examples' }
        ]
      }
    ]
  }
})

导航栏

导航栏是项目文档中的另一个重要部分，它能够协助用户快速定位到自己想要的内容。VitePress 的导航栏装备十分简略，只需求在装备文件中增加 nav 字段即可。

// .vitepress/config.mjs
import { defineConfig } from 'vitepress'
// https://vitepress.dev/reference/site-config
export default defineConfig({
  themeConfig: {
    nav: [
      { text: 'Home', link: '/' },
      { text: 'Examples', link: '/markdown-examples' }
    ]
  }
})

编写文档

Markdown

VitePress 默许支撑 Markdown 语法，你能够在文档中运用 Markdown 语法来编写文档。

# Hello World
This is my first VitePress site!

Vue 组件

VitePress 默许支撑 Vue 组件，你能够在文档中运用 Vue 组件来编写文档。

<script setup>
import { useData } from 'vitepress'
const { theme, page, frontmatter } = useData()
</script>
## Results
### Theme Data
<pre>{{ theme }}</pre>
### Page Data
<pre>{{ page }}</pre>
### Page Frontmatter
<pre>{{ frontmatter }}</pre>

你能够直接经过运用 Vue3 的 api 来编写你的文档。

写完文档后，记得去为你的新文档增加路由。

布置文档

我引荐运用 Vercel 来布置你的文档，它提供了免费的静态网站保管服务，你能够在它的官网上注册一个账号，然后创立一个项目，将你的文档上传到项目中，就能够经过 https://<your-project-name>.vercel.app 来拜访你的文档了。

Vercel 支撑十分多的结构预设，可是国内网络拜访起来可能会遇到少许阻止，能够经过设置自定义域名处理，或许能够测验 netlify, github pages, cloudflare pages 等其他的静态网站保管服务。

快速运用 vitepress 构建你的项目文档