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

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

VitePress 和 VuePress 一样,都是基于 vue 的静态站点生成器,但是 VitePress 采用了 vite 作为构建工具,相比 VuePress 基于 webpack 的构建工具,VitePress 的构建速度更快,同时也更轻量。

安装

准备条件

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

创建项目

首先我们需要创建一个项目目录,然后在项目目录中获取 vitepress:

bash 复制代码
mkdir vitepress-demo
cd vitepress-demo
npm add -D vitepress

然后我们可以通过官方提供的脚手架工具来创建项目:

bash 复制代码
npx vitepress init

根据你的情况选择需要修改的部分:

bash 复制代码
┌  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
└

此时的项目结构如下:

bash 复制代码
.
├── docs # 文档目录,根据上面你自己填写的路径
│   ├── api-examples.md
│   ├── index.md
│   └── markdown-examples.md
├── node_modules
│   ├── ...
├── package.json
└── package-lock.json

启动项目

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

bash 复制代码
npm run docs:dev

当你看到以下输出时,说明项目启动成功:

bash 复制代码
  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,我们可以在这个文件中配置一些项目的基本信息,比如标题、描述、主题等。

js 复制代码
// .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 字段即可。

js 复制代码
// .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 字段即可。

js 复制代码
// .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 语法来编写文档。

md 复制代码
# Hello World

This is my first VitePress site!

Vue 组件

VitePress 默认支持 Vue 组件,你可以在文档中使用 Vue 组件来编写文档。

md 复制代码
<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 等其他的静态网站托管服务。

相关推荐
庸俗今天不摸鱼30 分钟前
【万字总结】前端全方位性能优化指南(十)——自适应优化系统、遗传算法调参、Service Worker智能降级方案
前端·性能优化·webassembly
黄毛火烧雪下37 分钟前
React Context API 用于在组件树中共享全局状态
前端·javascript·react.js
Apifox1 小时前
如何在 Apifox 中通过 CLI 运行包含云端数据库连接配置的测试场景
前端·后端·程序员
一张假钞1 小时前
Firefox默认在新标签页打开收藏栏链接
前端·firefox
高达可以过山车不行1 小时前
Firefox账号同步书签不一致(火狐浏览器书签同步不一致)
前端·firefox
m0_593758101 小时前
firefox 136.0.4版本离线安装MarkDown插件
前端·firefox
掘金一周1 小时前
金石焕新程 >> 瓜分万元现金大奖征文活动即将回归 | 掘金一周 4.3
前端·人工智能·后端
三翼鸟数字化技术团队1 小时前
Vue自定义指令最佳实践教程
前端·vue.js
Jasmin Tin Wei2 小时前
蓝桥杯 web 学海无涯(axios、ecahrts)版本二
前端·蓝桥杯
圈圈编码2 小时前
Spring Task 定时任务
java·前端·spring