十分钟用 vitepress 搭建项目文档

2023-02-10
北京
本文字数：2076 字
阅读完需：约 7 分钟

前言

前些天，用尽平生所学，写了一篇技术文章，https://xie.infoq.cn/article/a8117f7ada21a278579945e00，可惜掘金给的流量不多，点赞的人不多，评论的人几乎没有，收藏的人却不少，我想可能是万字长文看起来太吃力，于是花了 3 天时间用vitepress搭建了一个项目文档，方便大家查阅。

文档地址：yinzhuo19970516.github.io/

欢迎大家点赞，评论，收藏就算了，收藏了也不看。

现在，我准备花 10min 介绍一下,介绍一下这个vuepress的小兄弟，vitepress

vitepress 是什么

vitepress 是一款基于 vite vue3 的静态站点生成器

有什么问题看文档吧，推荐看英文文档，中文文档不全

遇到问题建议去 github gitee 搜索，目前这类的博客比较少

英文文档

中文文档

vitepress 怎么用

新建文件夹，文件夹下新建目录

.├─ docs │  └─ index.md

复制代码

初始化

 npm init npm i vitepress

复制代码

package.json 添加 script

"scripts": {  "dev": "vitepress dev docs --open",  "build": "vitepress build docs",  "serve": "vitepress serve docs"},

复制代码

运行

 npm run dev

复制代码

最基础的搭建就成功了

加配置文件

在 docs 目录下创建一个 .vuepress目录，如下结构

.├─ docs│  ├─ .vitepress│  │  └─ config.js│  └─ index.md└─ package.json

复制代码

配置项目介绍

以我配置的为例

export default {  title: 'vue-template',// 网站标题  description: 'vue-cli/二次封装/vue3/axios/多入口打包', //网站描述  ignoreDeadLinks: true,// 最好加上，构建时会忽略md中的外链  markdown: {    theme: 'material-palenight',//md主题    lineNumbers: true//md 加行号  },  lastUpdated: true,//显示最近更新时间  appearance: true,//可以选择深浅主题    // 主题配置  themeConfig: {    socialLinks: [//右上角图标和链接，icon 可用svg 配置      { icon: 'github', link: 'https://github.com/Yinzhuo19970516/vue-template' },      { icon: 'slack', link: 'https://juejin.cn/user/1011206428301774' }    ],    lastUpdatedText: '更新时间',    siteTitle: 'vue-template',    nav: [//右侧导航      { text: '首页', link: '/' },      { text: '项目简介', link: '/page/index' },      { text: '更新日志', link: 'https://github.com/Yinzhuo19970516/vue-template/blob/main/CHANGELOG.md' }    ],    // 侧边导航    sidebar: [      {        text: '项目简介',        items: [          { text: '为什么要写这个项目', link: '/page/why' },          { text: '多入口打包', link: '/page/pages' },          { text: '自动化生成项目基本模版', link: '/page/init' },          { text: 'Pinia',link:'/page/pinia'},          { text: '数据持久化',link:'/page/piniaPlugin'},          { text: 'axios二次封装',link:'/page/axios'},          { text: '路由跳转动画',link:'/page/router'},          { text: 'less sass的优化处理',link:'/page/less'},          { text: 'viewport适配方案',link:'/page/viewport'},          { text: '环境变量',link:'/page/env'},          { text: '兼容性处理方案',link:'/page/babel'},          { text: '总结', link: '/page/all' },        ]      }    ],    outlineTitle: '目录'  }}

复制代码

首页布局

首页就是进入我们博客会加载 docs/index.md,所以我们需要对其进行一个美化，我们 VitePress 默认主题提供了一个主页布局参考我的吧，具体的意思很明显了，首页还挺好看的。

---
layout: hometitle: vue-templatedescription: vue-cli/二次封装/vue3/axios/多入口打包
hero:  name: vue-template🎉  text:  tagline: 基于vue3,vue-cli4二次封装的移动端框架  actions:    - theme: brand      text: 开始      link: /page/index    - theme: alt      text: 访问github      link: https://github.com/Yinzhuo19970516/vue-template---

复制代码

运行

明暗交错，非常不错

npm run dev

复制代码

打包

npm run build

复制代码

默认在.vitepress/dist 目录下

部署到 GitHub Pages

先在 github 新建一个仓库，、仓库命名为 username.github.io 的形式，username 是你 github 的用户名。然后点击设置。

我的在这里：https://github.com/Yinzhuo19970516/Yinzhuo19970516.github.io可直接抄作业，setting->pages->Brach->save

把 dist 文件下的文件 push 到建立的仓库里即可。

自动化部署

vitepress 官方怕我们太累，提供给了一个脚本 deploy.sh 直接可以抄作业

我每次就是本地直接 zsh deploy.sh

过一会，https://yinzhuo19970516.github.io/这个网站就会有最近的更新

#!/usr/bin/env sh
# 确保脚本抛出遇到的错误set -e
# 生成静态文件npm run build
# 进入生成的文件夹cd docs/.vitepress/dist
git initgit add -Agit commit -m 'deploy'
git push -f git@github.com:Yinzhuo19970516/Yinzhuo19970516.github.io.git mastercd -

复制代码

总结

还不错的一个文档框架，后续会在上面主要更新我的项目文档，有兴趣可以一起讨论，一起学习。

仓库地址

文档地址

发布于: 刚刚阅读数: 3

原文链接:【http://xie.infoq.cn/article/59c3cbb6ee176f9f17fbfa98e】。文章转载请联系作者。

虎妞先生

关注

还未添加个人签名 2017-12-22 加入

还未添加个人简介

发布

暂无评论

创作场景

十分钟用 vitepress 搭建项目文档

前言

vitepress 是什么

vitepress 怎么用

新建文件夹，文件夹下新建目录

初始化

运行

加配置文件

配置项目介绍

首页布局

运行

打包

部署到 GitHub Pages

自动化部署

总结

虎妞先生

评论