快速使用 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 等其他的静态网站托管服务。

相关推荐
DN金猿6 分钟前
使用npm install或cnpm install报错解决
前端·npm·node.js
丘山子7 分钟前
一些鲜为人知的 IP 地址怪异写法
前端·后端·tcp/ip
志存高远6619 分钟前
Kotlin 的 suspend 关键字
前端
www_pp_31 分钟前
# 构建词汇表:自然语言处理中的关键步骤
前端·javascript·自然语言处理·easyui
天天扭码1 小时前
总所周知,JavaScript中有很多函数定义方式,如何“因地制宜”?(ˉ﹃ˉ)
前端·javascript·面试
一个专注写代码的程序媛1 小时前
为什么vue的key值,不用index?
前端·javascript·vue.js
vvilkim1 小时前
React 与 Vue:两大前端框架的深度对比
vue.js·react.js·前端框架
장숙혜1 小时前
ElementUi的Dropdown下拉菜单的详细介绍及使用
前端·javascript·vue.js
火柴盒zhang1 小时前
websheet之 编辑器
开发语言·前端·javascript·编辑器·spreadsheet·websheet
某公司摸鱼前端1 小时前
uniapp 仿企微左边公司切换页
前端·uni-app·企业微信