devbox
知新_RL
这个屌丝很懒，什么也没留下！
关注作者
热门标签
热门文章
当前位置:   article > 正文

使用VitePress静态网站生成器创建组件库文档网站并部署到GitHub_vitepress组件库文档

作者：知新_RL | 2024-05-15 19:49:27

赞

踩

vitepress组件库文档

Vue3+TS+Vite开发组件库并发布到npm

网站在线预览：

Vue Amazing UI | Amazing UI Components LibraryAmazing UI 组件库https://themusecatcher.github.io/vue-amazing-ui/参考文档： 

一、安装依赖及配置

1、安装 vitepress

推荐使用 pnpm，安装pnpm：

npm install -g pnpm

安装vitepress： 

  1. pnpm add vitepress -D
  2. # or
  3. yarn add vitepress -D

2、在 package.json 中添加指令

在 script 中添加文档网站启动和打包指令，启动时指定端口 8000，并自动打开

  1. "scripts": {
  2.     "docs:dev": "vitepress dev docs --port 8000 --open",
  3.     "docs:build": "vitepress build docs"
  4. }

完整 package.json 文件如下： 

  1. {
  2.   "name": "vue-amazing-ui",
  3.   "version": "0.0.30",
  4.   "private": false,
  5.   "type": "module",
  6.   "files": [
  7.     "dist"
  8.   ],
  9.   "main": "./dist/vue-amazing-ui.umd.cjs",
  10.   "module": "./dist/vue-amazing-ui.js",
  11.   "exports": {
  12.     "./dist/style.css": "./dist/style.css",
  13.     "./css": "./dist/style.css",
  14.     ".": {
  15.       "import": "./dist/vue-amazing-ui.js",
  16.       "require": "./dist/vue-amazing-ui.umd.cjs"
  17.     }
  18.   },
  19.   "scripts": {
  20.     "dev": "vite --port 9000 --open --force",
  21.     "build": "run-p type-check build-only",
  22.     "docs:dev": "vitepress dev docs --port 8000 --open",
  23.     "docs:build": "vitepress build docs",
  24.     "docs:deploy": "sh script/deploy.sh",
  25.     "pub": "sh script/publish.sh",
  26.     "preview": "vite preview",
  27.     "build-only": "vite build",
  28.     "type-check": "vue-tsc --noEmit",
  29.     "lint": "eslint . --ext .vue,.js,.jsx,.cjs,.mjs,.ts,.tsx,.cts,.mts --fix --ignore-path .gitignore"
  30.   },
  31.   "dependencies": {
  32.     "@vuepic/vue-datepicker": "^4.5.1",
  33.     "@vueuse/core": "^10.1.2",
  34.     "@vueuse/integrations": "^10.1.2",
  35.     "ant-design-vue": "^3.2.20",
  36.     "core-js": "^3.30.2",
  37.     "date-fns": "^2.30.0",
  38.     "qrcode": "^1.5.3",
  39.     "swiper": "^9.3.2",
  40.     "vue": "^3.3.4",
  41.     "vue-amazing-ui": "^0.0.30",
  42.     "vue-router": "^4.2.1"
  43.   },
  44.   "devDependencies": {
  45.     "@rushstack/eslint-patch": "^1.3.0",
  46.     "@types/node": "^18.16.14",
  47.     "@vitejs/plugin-vue": "^4.2.3",
  48.     "@vue/eslint-config-typescript": "^11.0.3",
  49.     "@vue/tsconfig": "^0.1.3",
  50.     "eslint": "^8.41.0",
  51.     "eslint-plugin-vue": "^9.14.0",
  52.     "less": "^4.1.3",
  53.     "npm-run-all": "^4.1.5",
  54.     "prettier": "^2.8.8",
  55.     "rollup-plugin-visualizer": "^5.9.0",
  56.     "terser": "^5.17.6",
  57.     "typescript": "~4.7.4",
  58.     "unplugin-vue-components": "^0.25.0",
  59.     "vite": "^4.3.8",
  60.     "vitepress": "1.0.0-beta.1",
  61.     "vue-tsc": "^1.6.5"
  62.   },
  63.   "description": "This template should help get you started developing with Vue Amazing UI in Vue 3.",
  64.   "repository": {
  65.     "type": "git",
  66.     "url": "git+https://github.com/themusecatcher/vue-amazing-ui.git"
  67.   },
  68.   "keywords": [
  69.     "Vue3",
  70.     "TS",
  71.     "Vite",
  72.     "Amazing",
  73.     "UI",
  74.     "Components"
  75.   ],
  76.   "author": "theMuseCatcher",
  77.   "license": "ISC",
  78.   "bugs": {
  79.     "url": "https://github.com/themusecatcher/vue-amazing-ui/issues"
  80.   },
  81.   "homepage": "https://github.com/themusecatcher/vue-amazing-ui#readme"
  82. }

3、创建文档网站目录和文件

①创建 docs/ 目录

②在 docs/ 下新建 index.md 首页文件

③在 docs/ 下新建 public/ 文件夹

用于存放各种静态资源，例如：网站logo、首页图片等 

4、 启动项目

 启动后项目会在自动 /docs 下生成 .vitepress/ 目录

pnpm docs:dev

二、编写组件库文档

1、创建相关文件及目录

在 docs/.vitepress 中

创建 config.ts 配置文件

创建 theme/ 文件夹

在 theme/ 中创建 index.ts 文件

在 theme/ 中创建 global.less 存放全局样式（使用 less 文件需要安装相应依赖 ）

创建 utils/ 文件夹（用于存放自定义 ts 方法，一会首页自定义显示版本标签会用到）

（文档内使用了 less）安装 less 预处理器： 相关文档

pnpm add less -D

2、编写网站首页

首页配置参考文档

在 docs/index.md 中编写首页相关内容，其中 fetchVersion() 自定义方法用于在首页 tagline 后添加自定义版本标签

  1. ---
  2. layout: home
  3.  
  4. title: Vue Amazing UI
  5. titleTemplate: Amazing UI Components Library
  6.  
  7. hero:
  8.   name: Vue Amazing UI
  9.   text: Amazing UI 组件库
  10.   tagline: 基于 Vue3 + TS + Vite 开发
  11.   image:
  12.     src: /logo-with-shadow.png
  13.     alt: Vue Amazing UI
  14.   actions:
  15.     - theme: brand
  16.       text: Get Started
  17.       link: /guide/features
  18.     - theme: alt
  19.       text: View on GitHub
  20.       link: https://github.com/themusecatcher/vue-amazing-ui
  21.     - theme: alt
  22.       text: View on NPM
  23.       link: https://www.npmjs.com/package/vue-amazing-ui
  24. ---
  25.  
  26. <script setup lang="ts">
  27. import { onMounted } from 'vue'
  28. import { fetchVersion } from './.vitepress/utils/fetchVersion'
  29.  
  30. onMounted(() => {
  31.   fetchVersion()
  32. })
  33. </script>

在 docs/.vitepress/utils/ 中创建 fetchVersion.ts 文件

  1. // 远程读取 github 仓库中 package.json 文件中的 version 版本号
  2. // 方式一：
  3.   // 读取规则：https://api.github.com/repos/<username>/<repo>/contents/<file>?ref=<branch 可选，默认master>
  4.   // return fetch('https://api.github.com/repos/themusecatcher/vue-amazing-ui/contents/package.json?ref=master', {
  5.   //   headers: {
  6.   //     // See https://docs.github.com/en/rest/overview/media-types
  7.   //     Accept: 'application/vnd.github.v3.raw',
  8.   //     // See https://docs.github.com/en/rest/guides/getting-started-with-the-rest-api#authentication
  9.   //     // Authorization: 'token ${GITHUB_TOKEN}',
  10.   //   }
  11.   // })
  12.   // 方式二：
  13.   // 读取规则：https://raw.githubusercontent.com/<username>/<repo>/<branch>/<file>
  14. export function fetchVersion() {
  15.   return fetch('https://raw.githubusercontent.com/themusecatcher/vue-amazing-ui/master/package.json')
  16.     .then(res => res.json())
  17.     .then(json => json.version ?? '')
  18.     .then(version => {
  19.       if (!version) return
  20.       const tagLineParagragh = document.querySelector('div.VPHero.has-image.VPHomeHero > div > div.main > p.tagline')
  21.       const docsVersionSpan = document.createElement('samp')
  22.       docsVersionSpan.classList.add('version-tag')
  23.       docsVersionSpan.innerText = version
  24.       tagLineParagragh?.appendChild(docsVersionSpan)
  25.     })
  26. }

在 docs/.vitepress/theme/global.less 中写入标签样式

  1. .version-tag {
  2.   font-size: 14px;
  3.   line-height: 1.571;
  4.   font-weight: bold;
  5.   padding: 4px 6px;
  6.   margin-left: 6px;
  7.   background: #bd34fe;
  8.   color: #FFF;
  9.   border-radius: 10px;
  10.   display: inline-block;
  11.   vertical-align: top;
  12.   margin-top: 4px;
  13. }

效果如下图，版本标签：0.0.30

3、编写文档全局样式

在 theme/global.less 中写入样式，以下样式皆源自 vite 官网项目中使用的全局样式，并稍加修改：

  1. /**
  2.  * Colors
  3.  * -------------------------------------------------------------------------- */
  4.  
  5. :root {
  6.   --vp-c-brand: #646cff;
  7.   --vp-c-brand-light: #747bff;
  8.   --vp-c-brand-lighter: #9499ff;
  9.   --vp-c-brand-lightest: #bcc0ff;
  10.   --vp-c-brand-dark: #535bf2;
  11.   --vp-c-brand-darker: #454ce1;
  12.   --vp-c-brand-dimm: rgba(100, 108, 255, 0.08);
  13.   --c-brand: #646cff;
  14.   --c-brand-light: #747bff;
  15. }
  16.  
  17. /**
  18.  * Component: Button
  19.  * -------------------------------------------------------------------------- */
  20.  
  21. :root {
  22.   --vp-button-brand-border: var(--vp-c-brand-light);
  23.   --vp-button-brand-text: var(--vp-c-white);
  24.   --vp-button-brand-bg: var(--vp-c-brand);
  25.   --vp-button-brand-hover-border: var(--vp-c-brand-light);
  26.   --vp-button-brand-hover-text: var(--vp-c-white);
  27.   --vp-button-brand-hover-bg: var(--vp-c-brand-light);
  28.   --vp-button-brand-active-border: var(--vp-c-brand-light);
  29.   --vp-button-brand-active-text: var(--vp-c-white);
  30.   --vp-button-brand-active-bg: var(--vp-button-brand-bg);
  31. }
  32.  
  33. /**
  34.  * Component: Home
  35.  * -------------------------------------------------------------------------- */
  36.  
  37. :root {
  38.   --vp-home-hero-name-color: transparent;
  39.   --vp-home-hero-name-background: -webkit-linear-gradient(
  40.     120deg,
  41.     #bd34fe 30%,
  42.     #41d1ff
  43.   );
  44.  
  45.   --vp-home-hero-image-background-image: linear-gradient(
  46.     -45deg,
  47.     #bd34fe 50%,
  48.     #47caff 50%
  49.   );
  50.   --vp-home-hero-image-filter: blur(40px);
  51. }
  52.  
  53. @media (min-width: 640px) {
  54.   :root {
  55.     --vp-home-hero-image-filter: blur(56px);
  56.   }
  57. }
  58.  
  59. @media (min-width: 960px) {
  60.   :root {
  61.     --vp-home-hero-image-filter: blur(72px);
  62.   }
  63. }
  64.  
  65. /**
  66.  * Component: Custom Block
  67.  * -------------------------------------------------------------------------- */
  68.  
  69. :root {
  70.   --vp-custom-block-tip-border: var(--vp-c-brand);
  71.   --vp-custom-block-tip-text: var(--vp-c-brand-darker);
  72.   --vp-custom-block-tip-bg: var(--vp-c-brand-dimm);
  73. }
  74.  
  75. .dark {
  76.   --vp-custom-block-tip-border: var(--vp-c-brand);
  77.   --vp-custom-block-tip-text: var(--vp-c-brand-lightest);
  78.   --vp-custom-block-tip-bg: var(--vp-c-brand-dimm);
  79. }
  80.  
  81. /**
  82.  * Component: Algolia
  83.  * -------------------------------------------------------------------------- */
  84.  
  85. .DocSearch {
  86.   --docsearch-primary-color: var(--vp-c-brand) !important;
  87. }
  88.  
  89. /**
  90.  * VitePress: Custom fix
  91.  * -------------------------------------------------------------------------- */
  92.  
  93. /*
  94.   Use lighter colors for links in dark mode for a11y.
  95.   Also specify some classes twice to have higher specificity
  96.   over scoped class data attribute.
  97. */
  98. .dark .vp-doc a,
  99. .dark .vp-doc a > code,
  100. .dark .VPNavBarMenuLink.VPNavBarMenuLink:hover,
  101. .dark .VPNavBarMenuLink.VPNavBarMenuLink.active,
  102. .dark .link.link:hover,
  103. .dark .link.link.active,
  104. .dark .edit-link-button.edit-link-button,
  105. .dark .pager-link .title {
  106.   color: var(--vp-c-brand-lighter);
  107. }
  108.  
  109. .dark .vp-doc a:hover,
  110. .dark .vp-doc a > code:hover {
  111.   color: var(--vp-c-brand-lightest);
  112.   opacity: 1;
  113. }
  114. .vp-doc a {
  115.   font-weight: normal;
  116. }
  117. .vp-doc p {
  118.   margin: 0;
  119. }
  120. /* Transition by color instead of opacity */
  121. .dark .vp-doc .custom-block a {
  122.   transition: color 0.25s;
  123. }
  124. a:hover {
  125.   text-decoration: none !important;
  126. }
  127. summary {
  128.   font-weight: 600;
  129.   &:hover {
  130.     cursor: pointer;
  131.     color: var(--vp-c-brand-lighter);
  132.   }
  133. }
  134. svg {
  135.   fill: var(--vp-c-text-1);
  136. }
  137. .VPNavBarTitle .title {
  138.   transition: all 0.25s;
  139.   &:hover {
  140.     color: var(--vp-c-brand);
  141.   }
  142. }
  143. .version-tag {
  144.   font-size: 14px;
  145.   line-height: 1.571;
  146.   font-weight: bold;
  147.   padding: 4px 6px;
  148.   margin-left: 6px;
  149.   background: #bd34fe;
  150.   color: #FFF;
  151.   border-radius: 10px;
  152.   display: inline-block;
  153.   vertical-align: top;
  154.   margin-top: 4px;
  155. }

4、引入默认主题、全局样式与组件库

安装组件库

pnpm add vue-amazing-ui

在 theme/index.ts 中引入默认主题、全局样式并全局注册组件库

  1. import DefaultTheme from 'vitepress/theme'
  2. import './global.less' // global less
  3. import VueAmazingUI from 'vue-amazing-ui'
  4. import 'vue-amazing-ui/css'
  5. // import VueAmazingUI from '../../../dist/vue-amazing-ui'
  6. // import '../../../dist/style.css'
  7.  
  8. export default {
  9.   extends: DefaultTheme, // or ...DefaultTheme
  10.   enhanceApp ({ app }) {
  11.     app.use(VueAmazingUI)
  12.   }
  13. }

5、 配置网站

在 docs/.vitepress/config.ts 中进行网站配置

  1. import { defineConfig } from 'vitepress'
  2.  
  3. export default defineConfig({
  4.   title: `Vue Amazing UI`,
  5.   description: 'Amazing UI 组件库',
  6.   base: '/vue-amazing-ui/',
  7.  
  8.   head: [ // 网站图标
  9.     ['link', { rel: 'icon', type: 'image/svg+xml', href: 'logo.svg' }],
  10.     // ['link', { rel: 'icon', type: 'image/x-icon', href: 'favicon.ico' }],
  11.   ],
  12.   appearance: true, // 默认 true，设为 false 则无法切换dark/light主题，可选 'dark' true false
  13.   markdown: {
  14.     lineNumbers: false // 是否显示行数，默认false
  15.   },
  16.   themeConfig: {
  17.     logo: '/logo.svg',
  18.  
  19.     editLink: {
  20.       pattern: 'https://github.com/themusecatcher/vue-amazing-ui/tree/master/docs/:path',
  21.       text: 'Suggest changes to this page',
  22.     },
  23.     // 默认支持icon包括：'discord'|'facebook'|'github'|'instagram'|'linkedin'|'mastodon'|'slack'|'twitter'|'youtube'
  24.     socialLinks: [
  25.       { icon: 'github', link: 'https://github.com/themusecatcher/vue-amazing-ui' },
  26.       // 自定义icon
  27.       // {
  28.       //   icon: {
  29.       //     svg: '<svg role="img" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg"><title>Dribbble</title><path d="M12...6.38z"/></svg>'
  30.       //   },
  31.       //   link: 'https://www.npmjs.com/package/vue-amazing-ui'
  32.       // }
  33.     ],
  34.  
  35.     // search: { // vitepress 内置 search
  36.     //   provider: 'local'
  37.     // },
  38.  
  39.     algolia: { // algolia 搜索服务 与 内置 search 可二选一
  40.       appId: 'SHDNEYGA8Z',
  41.       apiKey: '91419401b0b0efd31b610e54e5b97249',
  42.       indexName: 'vue-amazing-ui'
  43.     },
  44.  
  45.     footer: {
  46.       message: 'Released under the MIT License.',
  47.       copyright: 'Copyright © 2023-present The Muse Catcher',
  48.     },
  49.  
  50.     nav: [
  51.       { text: '组件', link: '/guide/features', activeMatch: '/guide/' },
  52.       { text: '工具', link: '/utils/started', activeMatch: '/utils/' },
  53.       {
  54.         text: '链接',
  55.         items: [
  56.           { text: 'My Github', link: 'https://github.com/themusecatcher' },
  57.           { text: 'My CSDN', link: 'https://blog.csdn.net/Dandrose?type=blog' },
  58.           {
  59.             items: [
  60.               {
  61.                 text: 'vue',
  62.                 link: 'https://cn.vuejs.org/',
  63.               },
  64.               {
  65.                 text: 'vitepress',
  66.                 link: 'https://vitepress.dev/',
  67.               }
  68.             ]
  69.           }
  70.         ]
  71.       }
  72.     ],
  73.  
  74.     sidebar: {
  75.       '/guide/': [
  76.         {
  77.           text: '指引',
  78.           items: [
  79.             {
  80.               text: '特性',
  81.               link: '/guide/features'
  82.             },
  83.             {
  84.               text: '快速上手',
  85.               link: '/guide/started'
  86.             }
  87.           ]
  88.         },
  89.         {
  90.           text: '组件',
  91.           items: [
  92.             {
  93.               text: '面包屑 Breadcrumb',
  94.               link: '/guide/components/breadcrumb'
  95.             },
  96.             {
  97.               text: '按钮 Button',
  98.               link: '/guide/components/button'
  99.             },
  100.             {
  101.               text: '走马灯 Carousel',
  102.               link: '/guide/components/carousel'
  103.             },
  104.             {
  105.               text: '级联选择 Cascader',
  106.               link: '/guide/components/cascader'
  107.             },
  108.             {
  109.               text: '多选框 Checkbox',
  110.               link: '/guide/components/checkbox'
  111.             },
  112.             {
  113.               text: '折叠面板 Collapse',
  114.               link: '/guide/components/collapse'
  115.             },
  116.             {
  117.               text: '倒计时 Countdown',
  118.               link: '/guide/components/countdown'
  119.             },
  120.             {
  121.               text: '日期选择 DatePicker',
  122.               link: '/guide/components/datepicker'
  123.             },
  124.             {
  125.               text: '对话框 Dialog',
  126.               link: '/guide/components/dialog'
  127.             },
  128.             {
  129.               text: '分割线 Divider',
  130.               link: '/guide/components/divider'
  131.             },
  132.             {
  133.               text: '空状态 Empty',
  134.               link: '/guide/components/empty'
  135.             },
  136.             {
  137.               text: '图片 Image',
  138.               link: '/guide/components/image'
  139.             },
  140.             {
  141.               text: '数字输入框 InputNumber',
  142.               link: '/guide/components/inputnumber'
  143.             },
  144.             {
  145.               text: '全局提示 Message',
  146.               link: '/guide/components/message'
  147.             },
  148.             {
  149.               text: '信息提示 Modal',
  150.               link: '/guide/components/modal'
  151.             },
  152.             {
  153.               text: '通知提醒框 Notification',
  154.               link: '/guide/components/notification'
  155.             },
  156.             {
  157.               text: '分页器 Pagination',
  158.               link: '/guide/components/pagination'
  159.             },
  160.             {
  161.               text: '进度条 Progress',
  162.               link: '/guide/components/progress'
  163.             },
  164.             {
  165.               text: '二维码 QRCode',
  166.               link: '/guide/components/qrcode'
  167.             },
  168.             {
  169.               text: '单选框 Radio',
  170.               link: '/guide/components/radio'
  171.             },
  172.             {
  173.               text: '评分 Rate',
  174.               link: '/guide/components/rate'
  175.             },
  176.             {
  177.               text: '选择器 Select',
  178.               link: '/guide/components/select'
  179.             },
  180.             {
  181.               text: '滑动输入条 Slider',
  182.               link: '/guide/components/slider'
  183.             },
  184.             {
  185.               text: '加载中 Spin',
  186.               link: '/guide/components/spin'
  187.             },
  188.             {
  189.               text: '步骤条 Steps',
  190.               link: '/guide/components/steps'
  191.             },
  192.             {
  193.               text: '触摸滑动插件 Swiper',
  194.               link: '/guide/components/swiper'
  195.             },
  196.             {
  197.               text: '开关 Switch',
  198.               link: '/guide/components/switch'
  199.             },
  200.             {
  201.               text: '表格 Table',
  202.               link: '/guide/components/table'
  203.             },
  204.             {
  205.               text: '标签页 Tabs',
  206.               link: '/guide/components/tabs'
  207.             },
  208.             {
  209.               text: '文字滚动 TextScroll',
  210.               link: '/guide/components/textscroll'
  211.             },
  212.             {
  213.               text: '时间轴 Timeline',
  214.               link: '/guide/components/timeline'
  215.             },
  216.             {
  217.               text: '文字提示 Tooltip',
  218.               link: '/guide/components/tooltip'
  219.             },
  220.             {
  221.               text: '上传 Upload',
  222.               link: '/guide/components/upload'
  223.             },
  224.             {
  225.               text: '播放器 Video',
  226.               link: '/guide/components/video'
  227.             },
  228.             {
  229.               text: '瀑布流 Waterfall',
  230.               link: '/guide/components/waterfall'
  231.             }
  232.           ]
  233.         }
  234.       ],
  235.       '/utils/': [
  236.         {
  237.           text: '指引',
  238.           items: [
  239.             {
  240.               text: '快速上手',
  241.               link: '/utils/started'
  242.             }
  243.           ]
  244.         },
  245.         {
  246.           text: '工具',
  247.           items: [
  248.             {
  249.               text: 'date 日期格式化',
  250.               link: '/utils/date-format'
  251.             },
  252.             {
  253.               text: 'raf 动画帧',
  254.               link: '/utils/animation-frame'
  255.             },
  256.             {
  257.               text: 'raf 定时器',
  258.               link: '/utils/raf-timeout'
  259.             },
  260.             {
  261.               text: 'throttle 节流',
  262.               link: '/utils/throttle'
  263.             },
  264.             {
  265.               text: 'debounce 防抖',
  266.               link: '/utils/debounce'
  267.             },
  268.             {
  269.               text: 'add 加法',
  270.               link: '/utils/add'
  271.             },
  272.             {
  273.               text: 'downloadFile 下载文件',
  274.               link: '/utils/download-file'
  275.             }
  276.           ]
  277.         }
  278.       ]
  279.     }
  280.   }
  281. })

6、配置 Algolia 搜索

①申请搜索服务

申请地址 

填写部署到公网的网站地址、邮箱和代码仓库地址，全部勾选，然后提交！

②等待申请通过的邮件

③回复邮件

I am the maintainer of the website, I can modify the code ~

④等待回复邮件

获取 appId、apiKey、indexName

⑤配置并引入 algolia 搜索服务

 在 docs/.vitepress/config.ts 中写入以下配置 

  1. import { defineConfig } from 'vitepress'
  2.  
  3. export default defineConfig({
  4.   themeConfig: {
  5.     algolia: {
  6.       appId: 'SHDNEYGA8Z',
  7.       apiKey: '91419401b0b0efd31b610e54e5b97249',
  8.       indexName: 'vue-amazing-ui'
  9.     }
  10.   }
  11. })

algolia 搜索效果如下图：

网站整体目录结构如下图：

网站首页效果如下图：

 三、网站内容目录

1、创建内容目录文件

在 docs/ 下新建 /guide 文件夹

注意：目录结构需要与 docs/.vitepress/config.ts 配置文件中的 sidebar 属性相对应

创建 components/ 目录用于存放每个组件对应的文档页

创建 features.md 和 started.md 用与编写网站指引中的 特性 和 快速上手页面

features.md 文件：

  1. # 特性
  2.  
  3. ## 简要介绍
  4.  
  5. 该组件库采用 Vue3 + TS + Vite3 + Less 实现！
  6.  
  7. 开箱即用！
  8.  
  9. ## 三种使用方式
  10.  
  11. - 全局引入所有组件
  12. - 按需引入部分组件
  13. - git clone [vue-amazing-ui](https://github.com/themusecatcher/vue-amazing-ui) 到本地后，从 packages 下单独拷贝单文件组件 (SFC) 到项目内使用

started.md 文件：

  1. # 快速上手
  2.  
  3. ## 安装
  4.  
  5. **With PNPM**
  6.  
  7. ```bash
  8. $ pnpm i vue-amazing-ui
  9. # or
  10. $ pnpm add vue-amazing-ui
  11. ```
  12.  
  13. **With Yarn**
  14.  
  15. ```bash
  16. $ yarn add vue-amazing-ui
  17. ```
  18.  
  19. **With NPM**
  20.  
  21. ```bash
  22. $ npm i vue-amazing-ui
  23. ```
  24.  
  25. ## 使用
  26.  
  27. **Global**
  28.  
  29. ```ts
  30. import { createApp } from 'vue'
  31. import App from './App.vue'
  32.  
  33. import VueAmazingUI from 'vue-amazing-ui'
  34. import 'vue-amazing-ui/css'
  35.  
  36. const app = createApp(App)
  37. app.use(VueAmazingUI)
  38.  
  39. app.mount('#app')
  40. ```
  41.  
  42. **Local**
  43.  
  44. ```vue
  45. <script setup lang="ts">
  46. import { Button } from 'vue-amazing-ui'
  47. import 'vue-amazing-ui/css'
  48. </script>
  49.  
  50. <template>
  51.   <Button></Button>
  52. </template>
  53. ```

2、创建各个组件文档

在 components/ 目录下分别创建组件对应 md 文件

例如：编写 面包屑 breadcrumb 组件文档：

  1. # 面包屑 Breadcrumb
  2.  
  3. <br/>
  4.  
  5. *显示当前页面在系统层级结构中的位置，并能向上返回*
  6.  
  7. ## 何时使用
  8.  
  9. - 当系统拥有超过两级以上的层级结构时
  10. - 当需要告知用户『你在哪里』时
  11. - 当需要向上导航的功能时
  12.  
  13. <script setup lang="ts">
  14. const routes = [
  15.     {
  16.       path: '/first', // 路由地址
  17.       query: { id: 1, tab: 2 }, // 路由参数
  18.       name: '一级路由' // 路由名称
  19.     },
  20.     {
  21.       path: '/second',
  22.       name: '二级路由'
  23.     },
  24.     {
  25.       path: '/third',
  26.       name: '三级路由三级路由三级路由三级路由'
  27.     }
  28.   ]
  29. </script>
  30.  
  31. ## 基本使用
  32.  
  33. <Breadcrumb :routes="routes" />
  34.  
  35. ::: details Show Code
  36.  
  37. ```vue
  38. <script setup lang="ts">
  39. const routes = [
  40.     {
  41.       path: '/first', // 路由地址
  42.       query: { id: 1, tab: 2 }, // 路由参数
  43.       name: '一级路由' // 路由名称
  44.     },
  45.     {
  46.       path: '/second',
  47.       name: '二级路由'
  48.     },
  49.     {
  50.       path: '/third',
  51.       name: '三级路由三级路由三级路由三级路由'
  52.     }
  53.   ]
  54. </script>
  55. <template>
  56.   <Breadcrumb :routes="routes" />
  57. </template>
  58. ```
  59.  
  60. :::
  61.  
  62. ## 自定义分隔符
  63.  
  64. <Breadcrumb :routes="routes" separator="/" />
  65.  
  66. ::: details Show Code
  67.  
  68. ```vue
  69. <script setup lang="ts">
  70. const routes = [
  71.     {
  72.       path: '/first', // 路由地址
  73.       query: { id: 1, tab: 2 }, // 路由参数
  74.       name: '一级路由' // 路由名称
  75.     },
  76.     {
  77.       path: '/second',
  78.       name: '二级路由'
  79.     },
  80.     {
  81.       path: '/third',
  82.       name: '三级路由三级路由三级路由三级路由'
  83.     }
  84.   ]
  85. </script>
  86. <template>
  87.   <Breadcrumb :routes="routes" separator="/" />
  88. </template>
  89. ```
  90.  
  91. :::
  92.  
  93. ## 自定义样式
  94.  
  95. <Breadcrumb :routes="routes" :font-size="16" />
  96.  
  97. ::: details Show Code
  98.  
  99. ```vue
  100. <script setup lang="ts">
  101. const routes = [
  102.     {
  103.       path: '/first', // 路由地址
  104.       query: { id: 1, tab: 2 }, // 路由参数
  105.       name: '一级路由' // 路由名称
  106.     },
  107.     {
  108.       path: '/second',
  109.       name: '二级路由'
  110.     },
  111.     {
  112.       path: '/third',
  113.       name: '三级路由三级路由三级路由三级路由三级路由'
  114.     }
  115.   ]
  116. </script>
  117. <template>
  118.   <Breadcrumb :routes="routes" :font-size="16" />
  119. </template>
  120. ```
  121.  
  122. :::
  123.  
  124. ## 新页面打开目标链接
  125.  
  126. <Breadcrumb :routes="routes" target="_blank" />
  127.  
  128. ::: details Show Code
  129.  
  130. ```vue
  131. <script setup lang="ts">
  132. const routes = [
  133.     {
  134.       path: '/first', // 路由地址
  135.       query: { id: 1, tab: 2 }, // 路由参数
  136.       name: '一级路由' // 路由名称
  137.     },
  138.     {
  139.       path: '/second',
  140.       name: '二级路由'
  141.     },
  142.     {
  143.       path: '/third',
  144.       name: '三级路由三级路由三级路由三级路由'
  145.     }
  146.   ]
  147. </script>
  148. <template>
  149.   <Breadcrumb :routes="routes" target="_blank" />
  150. </template>
  151. ```
  152.  
  153. :::
  154.  
  155. ## APIs
  156.  
  157. 参数 | 说明 | 类型 | 默认值 | 必传
  158. -- | -- | -- | -- | --
  159. routes | 路由数组 | Route[] | [] | true
  160. fontSize | 字体大小，单位px | number | 14 | false
  161. height | 面包屑高度 | number | 36 | false
  162. maxWidth | 文本最大显示宽度，超出后显示省略号，单位px | 180 | false
  163. separator | 分隔符，默认''时为箭头 | string | '' | false
  164. target | 如何打开目标URL | '_self' &#124; '_blank' | '_self' | false
  165.  
  166. ## Route Type
  167.  
  168. 名称 | 说明 | 类型 | 必传
  169. -- | -- | -- | --
  170. path | 路由地址 | string | true
  171. query | 路由查询参数 | [propName: string]: any | false
  172. name | 路由名称 | string | true

四、打包静态网站并部署到 GitHub

1、创建脚本目录

在项目根目录 创建 script/ 目录，主要用于存放各种脚本文件，方便日后自动化开发流程！

创建 deploy.sh 用于打包静态网站，并部署到 Github

创建 publish.sh 用于打包升级组件库 ，并发布到 npm，同时自动升级项目内组件库依赖版本到最新

deploy.sh 文件：

  1. # /bin/bash
  2.  
  3. # 确保脚本抛出遇到的错误
  4. set -e
  5.  
  6. # 重新打包组件库
  7.  
  8. pnpm build
  9.  
  10. # 打包生成静态文件
  11. pnpm docs:build
  12.  
  13. # 进入待发布的 dist/ 目录
  14. cd docs/.vitepress/dist
  15.  
  16. git init
  17. git add .
  18. git commit -m 'deploy'
  19.  
  20. # 部署到 https://<username>.github.io/<repo>
  21. git push -f git@github.com:themusecatcher/vue-amazing-ui.git master:github-pages
  22.  
  23. # 提交所有代码到github
  24. cd ../../../
  25. git add .
  26. git cm -m 'update'
  27. git push

publish.sh 文件（需提前登录 npm 账户，否则无法直接发布）： 

  1. # /bin/bash
  2.  
  3. # 确保脚本抛出遇到的错误
  4. set -e
  5.  
  6.  # 读取package.json中的version
  7. version=`jq -r .version package.json`
  8.  
  9.  # 打包构建
  10. pnpm build
  11.  
  12.  # 提交代码到github
  13. git add .
  14. git commit -m "update $version"
  15. git push
  16.  
  17.  # 发布到npm，pnpm(高性能的npm)
  18. pnpm publish
  19.  
  20. # 升级 vue-amazing-ui 依赖版本
  21. pnpm up vue-amazing-ui@$version
  22.  
  23. # 提交版本更新代码到github
  24. git add .
  25. git cm -m "update $version"
  26. git push

2、 在 package.json 添加指令

  1. "scripts": {
  2.     "docs:deploy": "sh script/deploy.sh",
  3.     "pub": "sh script/publish.sh"
  4. }

3、打包部署

pnpm docs:deploy

4、配置 github

5、查看网站

save 成功之后，点击 Visit site 打开查看网站：

查看网站内容： 

声明：本文内容由网友自发贡献，不代表【wpsshop博客】立场，版权归原作者所有，本站不承担相应法律责任。如您发现有侵权的内容，请联系我们。转载请注明出处：https://www.wpsshop.cn/w/知新_RL/article/detail/574698
推荐阅读
相关标签

Copyright © 2003-2013 www.wpsshop.cn 版权所有，并保留所有权利。

  

闽ICP备14008679号