前言
当我们写完组件库并发布了之后实现一个vue3组件库 - 打包和发布 - 掘金 (juejin.cn)，怎么能少了一个介绍如何使用的官网呢？
本篇就来聊聊如何编写组件库的文档网站并免费部署！让人人都可以访问。
最终效果是这样的:SSS UI Plus
由于部署的是国外站点，所以访问可以要点魔法，下面是网站的部分截图：
vitepress
如果是重0开始一个网站的话，那样太麻烦而且也太慢了！幸好现在市面上有许多现有框架，我们可以直接使用。这里涉及的是vue相关，那么无非是两种：vuepress 和 vitepress。
为什么是vitepress?
截止到现在（2023-08-02），适用于vue3的静态网站生成器也就vuepress2 和 vitepress 。并且两者都还是在快速迭代当中，更何况两者衍生出来的一些插件。
vitepress现在最优势的地方就在于，它是面向未来的。插件的开发者大部分会倾向于vitepress。就比如我们想要在网站是展示组件，到github上面搜索相关插件，vitepress相关的插件收藏量和数量远多余vuepress。总之就一句话：vitepress在未来比vuepress主流
注意
如果你想要展示的是vue2相关的组件、或者纯粹是想要搭建博客什么的，还是建议vuepress1, vitepress 和 vitepress目前还在迭代，很多功能还不完善且不稳定。
项目初始化
我们现在要做的是不依赖脚手架搭建一个项目，所有项目初始化是:
-
新建文件夹，作为项目根目录
-
对该文件夹初始化git、npm(如果你用的包管理是npm)
git init
npm init完成指令后你会得到下面的文件结构（其实就是一个.git文件，一个json文件）
.git是隐藏文件，你需要在查看中勾选隐藏的项目才能看见
安装vitepress
如果你很确信要使用最新的版本的vitepress、vue 的话。可以选择直接安装最新版：
npm i vitepress
但是由于vitepress还在快速迭代中，你也可以锁定vitepress和vue的版本。
项目目录结构
注意这里的很多文件夹和文件都要自己手动创建
ini
demo
├─ .git
├─ docs // 存放文档的目录，很重要！！里面的都要手动创建
│ ├─ .vitepress
│ │ ├─ config.ts //重要
│ │ └─ theme
│ │ └─ index.ts //重要
│ ├─ comps //存放表述组件的文档
│ │ └─ button
│ ├─ guide //存放指南文档
│ ├─ index.md //首页
│ └─ public //存放公共资源文件（运行时，里面的资源会映射到网站根目录）
├─ node_moudles
├─ .gitignore //git忽略文件 要手动创建
├─ package-lock.json
└─ package.json首先别忘了设置 .gitignore中的内容，因为最后项目要推送到github,之后在自动部署
.gitignore
/docs/.vitepress/cache
/docs/.vitepress/dist
node_modules然后是在package.json中设置scripts：
package.json
"scripts": {
"docs:dev": "vitepress dev docs",
"docs:build": "vitepress build docs",
"docs:preview": "vitepress preview docs"
},最后在docs->theme->index.ts中设置:
ts
import DefaultTheme from 'vitepress/theme';
export default {
...DefaultTheme, //这里是使用默认主题
NotFound: () => 'custom 404', // <- this is a Vue 3 functional component
enhanceApp({ app, router, siteData }) {
}
}index.md 首页
先在docs->index.md 中随便写点什么，然后启动项目
npm run docs:dev
不出意外的话，你将会启动一个服务，并且得到:
那么恭喜你，成功启动了项目，但是项目太丑怎么办？我们可以稍微修改一下docs->index.md
md
---
layout: home
title: home
hero:
name: SSS-UI
text: 适用于VUE3的组件库
tagline: 轻量,简约
image:
src: /styles/icon.svg # 这里最终引入的是`docs->public->styles/icon.svg`
alt: website logo
actions:
- theme: brand
text: 快速开始
link: /guide/
- theme: alt
text: github repository
link: https://github.com/lastertd/sss-ui-plus
features:
- icon: 🛠️
title: TypeScript
details: 让编译器具有智能提示，写代码tab tab tab💟
- icon: ✨
title: 支持按需引入
details: 代码大小down down down✨
- icon: ☘
title: VUE3
details: 适用于vue3版本，体验最新技术栈🧡
---
现在是不是首页漂亮多了？关于网站的logo,找一个喜欢的叭
config.ts配置
接下来应该配置网站的小标题、小图标、首页右上角网站名:
在docs->.vitepress->config.ts中设置:
ts
export default defineConfig({
title:"SSS UI Plus", //网站小标题
themeConfig: {
siteTitle:"SSS-UI", //首页右上角网站名
logo:'favicon.ico', //网站小图标
},
})然后是配置网站的导航栏部分，同样是config.ts
ts
export default defineConfig({
// site-level options
title:"SSS UI Plus",
themeConfig: {
siteTitle:"SSS-UI",
logo:'favicon.ico', //对应的其实是`docs->public->favicon.ico`
nav: [
{text: '指南', link: '/guide/', activeMatch: '/guide'},
{text: '组件', link: '/comps/button/', activeMatch: '/comps'},
],
socialLinks: [{ icon: "github", link: "https://github.com/lastertd/sss-ui-plus" }],
},
})socialLinks其实不能算是导航栏，但是出现的位置一样。
你将会得到:
此时你会发现我们点击指南 组件 快速开始 三个选项时，会404,因为我们此时还只是配置了导航，但是却没有有效的地址
解决很简单，观察点击了指南后的链接变化，他实际上是导航到项目的guide目录当中，此时guide目录还是空空如也，在guide目录下创建index.md即可
接着是侧边栏部分，侧边栏分为两种
- 文档目录导航
- 文档内部导航
像上图的右侧就是文档内部导航，他由vitepress自动生成，默认显示第二级标题
对于文档目录导航，则需要手动在config.ts中配置:
ts
import {defineConfig} from 'vitepress'
export default defineConfig({
// site-level options
title:"SSS UI Plus",
themeConfig: {
siteTitle:"SSS-UI",
logo:'favicon.ico',
nav: [
{text: '指南', link: '/guide/', activeMatch: '/guide'},
{text: '组件', link: '/comps/button/', activeMatch: '/comps'},
],
socialLinks: [{ icon: "github", link: "https://github.com/lastertd/sss-ui-plus" }],
sidebar:{
'/guide/':[
{
text:'指南',
items:[
{text:'安装',link:'/guide/'},
{text:'快速开始',link:'/guide/start'},
]
},
{
text:'侧边栏第二项',
items:[]
}
],
'/comps/':[
{
text:'基础组件',
items:[
{text:'Button 按钮',link:'/comps/button/'},
{text:'Link 链接',link:'/comps/link/'},
]
},
{
text:'反馈组件',
items:[
]
}
]
}
},
})这里sidebar的类型选择对象形式，因为我们需要侧边栏的地方不止guide一处
仔细观察你会发现，导航到安装和快速开始的link是不一样的
- /guide/ 指向guide/index.md
- /guide/start 指向guide/start.md
其实区别就是触发了一个简写，/abc/会导航向/abc/index.md 是不是和js很像？
ruabick
ruabick是一个用于在vitepress中展示vue3组件的一个插件，他的前身vitepress-for-component:居然有尤大大在贡献者中，说实话我惊了。
引入
你需要通过
npm i @ruabick/md-demo-plugins @ruabick/vitepress-demo-block -D
来安装它
在config.ts中
ts
import {defineConfig} from 'vitepress'
import { applyPlugins } from '@ruabick/md-demo-plugins';
export default defineConfig({
//省略之前的配置
markdown: {
config: (md) => {
applyPlugins(md);
}
},
vite: {
plugins: []
}
})同时在docs->.vitepress->theme->index.ts中:
ts
import DefaultTheme from 'vitepress/theme';
import DemoBlock from '@ruabick/vitepress-demo-block';
import '@ruabick/vitepress-demo-block/dist/style.css';
export default {
...DefaultTheme,
NotFound: () => 'custom 404', // <- this is a Vue 3 functional component
enhanceApp({ app, router, siteData }) {
app.component('demo', DemoBlock);
}
}使用
在使用之前，我们安装：
npm i sss-ui-plus
同时修改docs->.vitepress->theme-index.ts
ts
import DefaultTheme from 'vitepress/theme';
import "sss-ui-plus/dist/index.css"
import ui from "sss-ui-plus/es/index"
import DemoBlock from '@ruabick/vitepress-demo-block';
import '@ruabick/vitepress-demo-block/dist/style.css';
export default {
...DefaultTheme,
NotFound: () => 'custom 404', // <- this is a Vue 3 functional component
enhanceApp({ app, router, siteData }) {
app.use(ui);
app.component('demo', DemoBlock);
}
}- 在
comps目录中创建button目录 - 在
button目录中创建src目录和index.md - 在
src目录中创建basic.vue
修改basic.vue:
vue
<template>
<s-row horizontal="flex-start" gap="10">
<s-button type="default" >default</s-button>
<s-button type="primary" >primary</s-button>
<s-button type="success" >success</s-button>
<s-button type="info" >info</s-button>
<s-button type="danger" >danger</s-button>
<s-button type="warning" >waring</s-button>
<s-button type="cyan" >waring</s-button>
</s-row>
<s-row horizontal="flex-start" gap="10">
<s-button type="default" empty>default</s-button>
<s-button type="primary" empty >primary</s-button>
<s-button type="success" empty >success</s-button>
<s-button type="info" empty >info</s-button>
<s-button type="danger" empty >danger</s-button>
<s-button type="warning" empty >waring</s-button>
<s-button type="cyan" empty >waring</s-button>
</s-row>
<s-row horizontal="flex-start" gap="10">
<s-button type="default" round >default</s-button>
<s-button type="primary" round >primary</s-button>
<s-button type="success" round >success</s-button>
<s-button type="info" round >info</s-button>
<s-button type="danger" round >danger</s-button>
<s-button type="warning" round >waring</s-button>
<s-button type="cyan" round >waring</s-button>
</s-row>
<s-row horizontal="flex-start" gap="10">
<s-button type="default" circle prefix-icon="medal"></s-button>
<s-button type="primary" circle prefix-icon="eye"></s-button>
<s-button type="success" circle prefix-icon="option"></s-button>
<s-button type="info" circle prefix-icon="user2"></s-button>
<s-button type="danger" circle prefix-icon="close"></s-button>
<s-button type="warning" circle prefix-icon="editor"></s-button>
<s-button type="cyan" circle prefix-icon="upload"></s-button>
</s-row>
</template>修改button->index.md
md
# Button 按钮
常见的按钮
## 基础用法
使用 `type` `empty` `round` 来指定按钮最基本的样式
<demo
src="./src/basic.vue"
title="type取值一共有8种噢 , 1,2,3,4,5,6,7...还一种被藏了起来"
/>最后你会得到:
关于ruabick详细用法请查看官网:ruabick
vercel
vercel是一个自动部署的神仙网站 基本可以部署任何东西！！！，你只需要将代码放在github仓库中，vercel会帮你自动部署，当仓库改变时，vercel也是检测到并帮你重新部署，这一切都是免费的!!!!
首先，在本地执行
npm run docs:build
先测试本地是否能够打包成功，如果不能打包成功，请检查代码
然后是推送你的代码到github仓库中，比如:
然后是登录vercel官网并以github账号登录
点击右上角add new project 选择你刚刚创建的代码仓库 我这里是demo
点击import你需要的项目后， 不出意外的话vercel会自动检测到你的项目是vitepress
点击Deploy遍帮你自动部署成功了！
恭喜你，完成了网站的部署，关于vercel的更详细教程，请查询官网或者搜索教程。
注意，vercel在国外，如果要对国内用户友好的话，可以选择国内的在线部署方案
写在最后
首先，这个项目地址是lastertd/sss-ui-plus: 适用于vue3的组件库 (github.com) 在这里求一个star✨
其次，若是在网站编写和部署中遇到什么问题，欢迎在讨论区写下，大伙一起掉头发hhh
最后，感谢看到最后💟💟💟