实现一个vue3组件库 - 网站编写和部署

前言

当我们写完组件库并发布了之后实现一个vue3组件库 - 打包和发布 - 掘金 (juejin.cn),怎么能少了一个介绍如何使用的官网呢?

本篇就来聊聊如何编写组件库的文档网站并免费部署!让人人都可以访问。

最终效果是这样的:SSS UI Plus

由于部署的是国外站点,所以访问可以要点魔法,下面是网站的部分截图:

vitepress

如果是重0开始一个网站的话,那样太麻烦而且也太慢了!幸好现在市面上有许多现有框架,我们可以直接使用。这里涉及的是vue相关,那么无非是两种:vuepressvitepress

为什么是vitepress?

截止到现在(2023-08-02),适用于vue3的静态网站生成器也就vuepress2vitepress 。并且两者都还是在快速迭代当中,更何况两者衍生出来的一些插件。

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的版本。

npm i vue@3.3.4 vitepress@1.0.0-beta.7

项目目录结构

注意这里的很多文件夹和文件都要自己手动创建

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

最后,感谢看到最后💟💟💟

相关推荐
cronaldo914 分钟前
研发效能DevOps: Vite 使用 Element Plus
vue.js·vue·devops
vvw&14 分钟前
如何在 Ubuntu 22.04 上安装 Graylog 开源日志管理平台
linux·运维·服务器·ubuntu·开源·github·graylog
HelloGitHub2 小时前
跟着 8.6k Star 的开源数据库,搞 RAG!
开源·github
GitCode官方2 小时前
GitCode 光引计划投稿 | GoIoT:开源分布式物联网开发平台
分布式·开源·gitcode
m0_748256782 小时前
WebGIS实战开源项目:智慧机场三维可视化(学习笔记)
笔记·学习·开源
编程百晓君2 小时前
一文解释清楚OpenHarmony面向全场景的分布式操作系统
vue.js
暴富的Tdy3 小时前
【CryptoJS库AES加密】
前端·javascript·vue.js
neeef_se3 小时前
Vue中使用a标签下载静态资源文件(比如excel、pdf等),纯前端操作
前端·vue.js·excel
z千鑫3 小时前
【前端】入门指南:Vue中使用Node.js进行数据库CRUD操作的详细步骤
前端·vue.js·node.js
猫头虎3 小时前
新纪天工 开物焕彩:重大科技成就发布会参会感
人工智能·开源·aigc·开放原子·开源软件·gpu算力·agi