【开源心路历程】超详细vitePress搭建脚手架官网

JS心法
5,197 阅读7分钟

前言

大家好，我是阿江，书接上文，昨天写了一篇 创建一个属于你自己的脚手架 讲了如何从0搭建一个脚手架。当时留了一个官网的知识点，实际上因为官网上的文档实在太过简略，所以导致配置起来每一项都需要单独去google，所以今天单拎出来一片文章讲一下我用到的常用配置项，会尽量详细的去解释每一步的作用。

开始

既然我们脚手架的搭建有参考vite的模板源码，那这次我们搭建的文档官网自然也优先考虑使用vitepress了，毕竟不能光吃馒头不吃菜啊。

先说明一下我搭建的这个官网是基于上一篇文章的项目结构，加入的所以截图会出现之前结构，还请读者不要见怪。本文搭建的版本是 "vitepress": "^0.20.9" 的最新版本。

vitePress是干嘛

vitepress 用于快速搭建静态网页项目。一般用于开发文档较多，也可以自定义主题开发 官网、博客等项目。

并且基于.md文件 生成html支持makedown文本开发，并且支持vue组件使用开发、享受vite的热更新。

vitePress 的使用步骤

yarn 下载

yarn add --dev vitepress

npm 下载

npm i vitepress --save

创建一个放置页面的文件夹 如文档的话创建docs文件夹，如果是官网的话website文件夹 因人而异。相当于在项目的根目录创建一个文件夹。
接着在最外层创建一个index.md文件 或者使用此命令

 mkdir docs && echo '# Hello VitePress' > docs/index.md

image321.png 这是最外层初始化页面，也是第一个页面。

添加命令

在根路径下的package.json添加如下指令

"docs:dev": "vitepress dev docs",//启动指令
"docs:build": "vitepress build docs",//打包指令
"docs:serve": "vitepress serve docs"//测试运行打包后文件指令

需要注意的是这里的docs是根据你起的文件夹名字来的，如果你的名字是website那这里的命令应该是："website:dev": "vitepress dev website"

启动项目

yarn 启动

yarn docs:dev

npm 启动

npm run docs:dev

打开 http://localhost:3000/ 你会看到如下页面

image.png

设置配置

在刚刚创建的docs文件夹下创建一个.vitepress文件夹，内部创建一个config.js用于配置关于vitepress中所有的配置项。

目录层级如下：

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

或者在package.json的根目录下直接执行如下创建命令

cd docs && mkdir .vitepress && cd .vitepress && touch config.js

这里的意思就是进入docs目录->创建.vitepress文件夹->进入.vitepress文件夹->创建config.js

module.exports = {
    base:'/vue3-vite-cli/',  
    title: 'Vue3-Vite-Cli 中文文档', 
    //首页的描述
    description: '基于vite为基础搭建的风格脚手架,提供多种模板以便于更高效的解决业务需求！', 
    lang: 'zh-CN',
    head: [['link', { rel: 'icon', type: 'image/svg+xml', href: 'logo.jpeg' }]],
}

参数

如下参数包含vitePress文档没有写入的，大体是自己使用之后得到的经验理解，如有不对，还请指出！

base

base:'/vue3-vite-cli/',

该网站的基本 URL 将部署在。如果你计划将你的网站部署在一个子路径下，你需要设置这个，例如 GitHub 页面。如果你计划将你的网站部署到 foo.github.io/bar/ ，那么你应该将基地设置为/bar/。它应该始终以斜线开头和结尾

title

title: 'Vue3-Vite-Cli 中文文档',

网站的标题。这将是所有页面标题的后缀，并显示在导航栏中。

description

description: '基于vite为基础搭建的风格脚手架,提供多种模板以便于更高效的解决业务需求！',

网站的描述，默认显示在index.md(首页)中

lang

lang: 'zh-CN',

该网站的 lang 属性。这将在 HTML 页面中呈现为一个 <HTML lang="en-us"> 标记。

head

head: [['link', { rel: 'icon', type: 'image/svg+xml', href: 'logo.jpeg' }]],

该网站的 head 属性。数组的类型，二维数组为主，不会受到编译影响的引入。

//编译后引入到index.html效果
<link rel="icon" type="image/svg+xml" href="logo.jpeg">

这里的logo设置需要在docs层级中创建public文件夹存放静态资源 image.png

themeConfig

themeConfig:{
    repo: 'wushijiang13/vue3-vite-cli',
    repoLabel:'GitHub',
    docsDir: 'docs',
    docsBranch: 'master',
    editLinks: true,
    editLinkText: '欢迎帮助我们改善页面!',
    lastUpdated: '最近更新时间',
    nav: [
        { text: '入门', link: '/getting/why.html' },
        { text: '码云', link: 'https://gitee.com/wushijiang13/vue3-vite-cli' },
    ],
    sidebar: {
        '/': [
            {
                text: '入门',
                children: [
                    {
                        text: '简介',
                        link: '/getting/why.html'
                    },
                    {
                        text: '模板脚手架简介',
                        link: '/getting/template_introduction.html'
                    }
                ]
            }
        ]
    }
}

该网站主题配置对象,可配置导航栏，侧边功能栏，底部帮助栏，路由地址等。

repo

repo: 'wushijiang13/vue3-vite-cli',

文档项目对应的GitHub用户名/GitHub项目名 用于配置导航栏 GitHub 的跳转，也是用来配置所有页面中底部导航的帮助我们编辑GitHub修改跳转功能的必须项

image.png

repoLabel

repoLabel:'GitHub',

用于配置导航栏 GitHub 链接的名称，默认为 GitHub。

docsDir

docsDir: 'docs',

项目中放置文档文件夹的名称

docsBranch

docsBranch: 'master',

项目在GitHub仓库的分支，也是用来配置所有页面中底部导航的帮助我们编辑GitHub修改跳转功能的必须项

editLinks

editLinks: true,

控制项目中给全局显示帮助我们编辑GitHub修改跳转功能,也可以在每个md文件头部各自设置editLink: true 来控制。

editLinkText

editLinkText: '欢迎帮助我们改善页面!',

帮助我们修改的文案，默认文案是Edit this page。

image.png

lastUpdated

lastUpdated: '最近更新时间',

右下角显示最近更新时间文案，并控制显示。

image.png

nav

nav: [
    { text: '入门', link: '/getting/why.html' },
    { text: '码云', link: 'https://gitee.com/wushijiang13/vue3-vite-cli' },
],

该网站导航栏选项，text为标题 link为地址，可以填写本地相对路径也可以填写链接

sidebar

sidebar: {
    '/': [
        {
            text: '入门',
            children: [
                {
                    text: '简介',
                    link: '/getting/why.html'
                },
                {
                    text: '模板脚手架简介',
                    link: '/getting/template_introduction.html'
                }
            ]
        }
    ]
}

该网站侧边导航栏选项，’/‘代表默认匹配路径，如不设置其他匹配默认所有页面按照’/‘匹配下的侧边导航栏展示。text代表标题，children代表子集，效果如下：

image.png

另外读者也可以在每个.md文件中的头部设置sidebar: auto

image.png

这样设置会覆盖掉config.js文件中的默认路径配置
如下图

image.png 实现切换页面自动生成对应当前章节的侧边导航栏

完整配置

module.exports = {
    base:'/vue3-vite-cli/',
    title: 'Vue3-Vite-Cli 中文文档',
    description: '基于vite为基础搭建的风格脚手架,提供多种模板以便于更高效的解决业务需求！',
    lang: 'zh-CN',
    head: [['link', { rel: 'icon', type: 'image/svg+xml', href: 'logo.jpeg' }]],
    themeConfig:{
        repo: 'wushijiang13/vue3-vite-cli',
        repoLabel:'测试',
        docsDir: 'docs',
        docsBranch: 'master',
        editLinks: true,
        editLinkText: '欢迎帮助我们改善页面!',
        lastUpdated: '最近更新时间',
        nav: [
            { text: '入门', link: '/getting/why.html' },
            { text: '模板', link: '/template/template-vue3-ts-initial.html' },
            { text: '相关文档', link: '/documentation/vue.html' },
            { text: '码云', link: 'https://gitee.com/wushijiang13/vue3-vite-cli' },
        ],
        sidebar: {
            '/': [
                {
                    text: '入门',
                    children: [
                        {
                            text: '简介',
                            link: '/getting/why.html'
                        },
                        {
                            text: '模板脚手架简介',
                            link: '/getting/template_introduction.html'
                        }
                    ]
                },
                {
                    text: '模板内部结构解析',
                    children: [
                        {
                            text: 'vue3-ts-initial',
                            link: '/template/template-vue3-ts-initial.html'
                        },
                        {
                            text: 'webpack-protist-js',
                            link: '/template/template-webpack-protist-js.html'
                        }
                    ]
                },
                {
                    text: '相关文档',
                    children: [
                        {
                            text: 'Vue 相关文档',
                            link: '/documentation/vue.html'
                        },
                        {
                            text: 'Webpack 相关文档',
                            link: '/documentation/webpack.html'
                        }
                    ]
                }
            ]
        }
    }
}

以上就是我所常用的配置项，希望可以帮到大家。

index.md 头部配置

---
home: true //是否为主页

heroImage: /logo.jpeg //主页大图logo地址

actionText: 入门 //左边按钮
actionLink: /getting/why.html //跳转地址

altActionText: 模板文档 //右边按钮
altActionLink: /template/template-vue3-ts-initial.html //右边地址

footer: MIT Licensed | Copyright © 2019-present 吴先森出品 //底部描述
---

效果图如下

image.png

部署测试

还记得这两个命令吗？就是用来打包和测试打包服务测试

"docs:build": "vitepress build docs",
"docs:serve": "vitepress serve docs"

这里需要注意的是如果需要运行docs:serve测试打包后文件是否可用，切记注释掉base:'/vue3-vite-cli/'地址哦，否则会导致打开异常。如果没设置则不需要修改，最后测试完成还原注释即可。

由于笔者是部署到自己的云服务器上所以，上述所有涉及到路径的全部加上了.html，实际上如果读者只是部署到github则不需要设置这点。

附带github page部署方案

结语

以上就是笔者vitePress搭建脚手架官网的全部内容了，其实这段搭建文档的经历也算踩了不少的坑，主要文档的不全，导致配置起来需要左查右查。这里把笔者结出来。提供给正在使用他的人，笔者还是蛮开心的。
最后这里留下笔者的 成果地址
希望小伙伴们能点点star支持一下笔者。之后会给大家带来更好的文章！
一起努力一起进步，我是阿江！

写在最后

阿江，最近新建了一个前端摸鱼交流群，欢迎同好的小伙伴一起热闹热闹 快戳这里

avatar
文章
阅读
粉丝
相关推荐
vitepress+github actions搭建全自动部署高性能SSG网站
2.0k阅读
 · 
16点赞
「VitePress」极简博客搭建
6.0k阅读
 · 
9点赞
如何使用vitepress写一套自己的ui文档
4.4k阅读
 · 
5点赞
VitePress——创建个人文档
691阅读
 · 
0点赞
vitepress 最详细教程之Home Page的配置
2.8k阅读
 · 
8点赞
使用 vitepress + github Pages搭建自己的博客网站
3.9k阅读
 · 
22点赞
如何快速为 VitePress 添加 RSS 订阅支持
3.0k阅读
 · 
3点赞
Vuepress | 快速上手指南
4.0k阅读
 · 
66点赞
🌟 Vitepress 侧边栏自动生成，让你更专注写作
1.3k阅读
 · 
2点赞

友情链接：