feat: update documentation examples and styles for improved clarity and responsiveness

kieranwv · kieranwv · commit bc03fdf61862 · 2024-12-26T17:02:53.000+08:00
diff --git a/docs/.vitepress/components/Example.vue b/docs/.vitepress/components/Example.vue
@@ -1,8 +1,9 @@
 <script setup lang="ts">
+/// <reference types="vite/client" />
 import { useClipboard } from '@vueuse/core'
 import { useData } from 'vitepress'
 import { computed, ref } from 'vue'
-import { GITHUB_EDIT_URL } from '../config/constants'
+import { GITHUB_URL } from '../config/constants'
 import ExampleComponent from './ExampleComponent.vue'
 import ExampleOperate from './ExampleOperate.vue'
 import ExampleSourceCode from './ExampleSourceCode.vue'
@@ -24,12 +25,12 @@ const props = defineProps({
 
 const { isDark } = useData()
 
-const components = import.meta.glob('../../examples/**/*.vue', { eager: true })
+const components: Record<string, { default: any }> = import.meta.glob('../../examples/**/*.vue', { eager: true })
 
 const pathComponents = computed(() => {
-  const _obj = {}
+  const _obj: Record<string, any> = {}
   Object.keys(components).forEach((key) => {
-    _obj[key.replace('../../components/', '').replace('.vue', '')]
+    _obj[key.replace('../../examples/', '').replace('.vue', '')]
       = components[key].default
   })
   return _obj
@@ -55,7 +56,7 @@ const path = computed(() => {
 })
 
 function openHandle() {
-  window.open(`${GITHUB_EDIT_URL}/docs/${path.value}`)
+  window.open(`${GITHUB_URL}/blob/main/docs/examples/${path.value}.vue`)
 }
 </script>
 
diff --git a/docs/.vitepress/components/ExampleOperate.vue b/docs/.vitepress/components/ExampleOperate.vue
@@ -1,16 +1,40 @@
 <script setup lang="ts">
-import { ref } from 'vue'
+import { useData } from 'vitepress'
+import { computed, ref } from 'vue'
 
 const emit = defineEmits(['toggle', 'copy', 'open'])
 
+const { lang } = useData()
+
 const code = ref(false)
 
+const copy = ref(false)
+
+const codeText = computed(() => {
+  if (!code.value) {
+    return lang.value === 'en-US' ? 'Show Code' : '显示代码'
+  }
+  else {
+    return lang.value === 'en-US' ? 'Hide Code' : '隐藏代码'
+  }
+})
+
+const copyCodeText = computed(() => {
+  if (!copy.value) {
+    return lang.value === 'en-US' ? 'Copy Code' : '复制代码'
+  }
+  else {
+    return lang.value === 'en-US' ? 'Copied to clipboard' : '已复制到剪贴板'
+  }
+})
+
+const viewCodeText = computed(() => lang.value === 'en-US' ? 'View Source Code' : '查看源码')
+
 function toggleSourceCode() {
   code.value = !code.value
   emit('toggle')
 }
 
-const copy = ref(false)
 function copySourceCode() {
   copy.value = true
   setTimeout(() => {
@@ -26,7 +50,7 @@ function openSourceCode() {
 
 <template>
   <div class="example-operate">
-    <i class="icon" :title="!code ? '展示代码' : '隐藏代码'" @click="toggleSourceCode">
+    <i class="icon" :title="codeText" @click="toggleSourceCode">
       <svg v-if="!code" xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 32 32">
         <path
           fill="currentColor"
@@ -40,7 +64,7 @@ function openSourceCode() {
         />
       </svg>
     </i>
-    <i class="icon" :title="copy ? '已复制到剪贴板' : '复制代码'" @click="copySourceCode">
+    <i class="icon" :title="copyCodeText" @click="copySourceCode">
       <svg xmlns="http://www.w3.org/2000/svg" width="18" height="18" viewBox="0 0 32 32">
         <path
           fill="currentColor"
@@ -49,11 +73,11 @@ function openSourceCode() {
         <path fill="currentColor" d="M4 18H2V4a2 2 0 0 1 2-2h14v2H4Z" />
       </svg>
     </i>
-    <i class="icon" title="访问源码" @click="openSourceCode">
-      <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24">
+    <i class="icon" :title="viewCodeText" @click="openSourceCode">
+      <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 32 32">
         <path
-          fill="currentColor"
-          d="M5.544 2.673a1.549 1.549 0 0 1 1.8.097v.001c.246.198.426.466.515.769l1.446 4.428h5.39L16.14 3.54a1.54 1.54 0 0 1 .515-.769l.004-.004a1.554 1.554 0 0 1 1.795-.095l.002.001c.274.174.486.43.605.732l.004.01l2.473 6.451a5.45 5.45 0 0 1-1.813 6.303l-6.73 5.064h-.002a1.66 1.66 0 0 1-2 0l-6.731-5.065a5.452 5.452 0 0 1-1.806-6.294l2.48-6.469c.12-.302.333-.558.607-.732m.811 2.063L4.16 10.464c-.28.737-.337 1.604-.12 2.362c.217.755.671 1.42 1.295 1.896l6.66 5.01l6.653-5.005a3.65 3.65 0 0 0 1.308-1.904c.22-.76.159-1.638-.123-2.378l-2.189-5.71L16 9.769H8z"
+          fill="currentColor" fill-rule="evenodd"
+          d="M16 2a14 14 0 0 0-4.43 27.28c.7.13 1-.3 1-.67v-2.38c-3.89.84-4.71-1.88-4.71-1.88a3.7 3.7 0 0 0-1.62-2.05c-1.27-.86.1-.85.1-.85a2.94 2.94 0 0 1 2.14 1.45a3 3 0 0 0 4.08 1.16a2.93 2.93 0 0 1 .88-1.87c-3.1-.36-6.37-1.56-6.37-6.92a5.4 5.4 0 0 1 1.44-3.76a5 5 0 0 1 .14-3.7s1.17-.38 3.85 1.43a13.3 13.3 0 0 1 7 0c2.67-1.81 3.84-1.43 3.84-1.43a5 5 0 0 1 .14 3.7a5.4 5.4 0 0 1 1.44 3.76c0 5.38-3.27 6.56-6.39 6.91a3.33 3.33 0 0 1 .95 2.59v3.84c0 .46.25.81 1 .67A14 14 0 0 0 16 2"
         />
       </svg>
     </i>
@@ -83,7 +107,7 @@ function openSourceCode() {
   transition: all 0.3s ease-in-out;
 }
 
-.example-operate .icon:hover ::after {
+.example-operate .icon:hover::after {
   cursor: auto;
   content: attr(title);
   position: absolute;
diff --git a/docs/.vitepress/config/constants.ts b/docs/.vitepress/config/constants.ts
@@ -1,5 +1,3 @@
 export const GITHUB_URL = 'https://github.com/starter-collective/starter-lib-vue3'
 
-export const GITHUB_EDIT_URL = `${GITHUB_URL}/-/tree/master/`
-
 export const WEBSITE_URL = 'https://starter-lib-vue3.netlify.app/'
diff --git a/docs/.vitepress/config/en.ts b/docs/.vitepress/config/en.ts
@@ -1,12 +1,13 @@
 import { defineConfig } from 'vitepress'
 import pkg from '../../../package.json'
+import { GITHUB_URL } from './constants'
 
 export const en = defineConfig({
   lang: 'en-US',
   description: 'Vue 3 component library starter template, provides VitePress documentation, supports building ESM, CJS and IIFE formats.',
   themeConfig: {
     editLink: {
-      pattern: 'https://github.com/starter-collective/starter-lib-vue3/edit/main/docs/:path',
+      pattern: `${GITHUB_URL}/edit/main/docs/:path`,
       text: 'Edit this page on GitHub',
     },
     nav: [
@@ -17,7 +18,7 @@ export const en = defineConfig({
         items: [
           {
             text: 'Changelog',
-            link: 'https://github.com/starter-collective/starter-lib-vue3/releases',
+            link: `${GITHUB_URL}/releases`,
           },
         ],
       },
@@ -39,6 +40,9 @@ export const en = defineConfig({
         ],
       },
     ],
+    lastUpdated: {
+      text: 'Last Updated',
+    },
     footer: {
       message: 'Released under the MIT License.',
       copyright: 'Copyright © 2024-present Kieran Wang',
diff --git a/docs/.vitepress/config/index.ts b/docs/.vitepress/config/index.ts
@@ -14,12 +14,6 @@ export default defineConfig({
   // Vite config.
   // https://vitejs.dev
   vite: {
-    resolve: {
-      conditions: ['dev'],
-      alias: {
-        'starter-lib-vue3': '/src/index.ts',
-      },
-    },
     server: {
       host: true,
       port: 9865,
diff --git a/docs/.vitepress/config/shared.ts b/docs/.vitepress/config/shared.ts
@@ -19,7 +19,7 @@ export const shared = defineConfig({
   head: [
     ['link', { rel: 'icon', href: '/favicon.ico' }],
     ['link', { rel: 'icon', type: 'image/png', href: '/logo.png' }],
-    ['meta', { name: 'theme-color', content: '#FF057C' }],
+    ['meta', { name: 'theme-color', content: '#42b883' }],
     ['meta', { property: 'og:type', content: 'website' }],
     ['meta', { property: 'og:locale', content: 'en' }],
     ['meta', { property: 'og:title', content: 'Vue3 Component Library Starter Template' }],
diff --git a/docs/.vitepress/config/zh.ts b/docs/.vitepress/config/zh.ts
@@ -1,23 +1,24 @@
 import { defineConfig } from 'vitepress'
 import pkg from '../../../package.json'
+import { GITHUB_URL } from './constants'
 
 export const zh = defineConfig({
   lang: 'zh-CN',
   description: 'Vue 3 组件库启动模板，提供 VitePress 文档，支持构建 ESM、CJS 和 IIFE 格式。',
   themeConfig: {
     editLink: {
-      pattern: 'https://github.com/starter-collective/starter-lib-vue3/edit/main/docs/:path',
+      pattern: `${GITHUB_URL}/edit/main/docs/:path`,
       text: '在 GitHub 上编辑此页面',
     },
     nav: [
       { text: '指南', link: '/zh/guide/what-is', activeMatch: '/zh/guide/' },
-      { text: '函数', link: '/zh/components', activeMatch: '/zh/components/' },
+      { text: '组件', link: '/zh/components', activeMatch: '/zh/components/' },
       {
         text: `v${pkg.version}`,
         items: [
           {
-            text: 'Changelog',
-            link: 'https://github.com/starter-collective/starter-lib-vue3/releases',
+            text: '更新日志',
+            link: `${GITHUB_URL}/releases`,
           },
         ],
       },
@@ -39,6 +40,9 @@ export const zh = defineConfig({
         ],
       },
     ],
+    lastUpdated: {
+      text: '最后更新于',
+    },
     footer: {
       message: '基于 MIT 许可证发布。',
       copyright: '版权 © 2024-present Kieran Wang',
diff --git a/docs/.vitepress/theme/style.css b/docs/.vitepress/theme/style.css
@@ -1,5 +1,5 @@
 :root {
-  --vp-c-brand-1: #44bd87;
+  --vp-c-brand-1: #42b883;
   --vp-c-brand-2: #249252;
   --vp-c-brand-3: #19633b;
   --vp-home-hero-name-color: transparent;
@@ -29,3 +29,12 @@ html {
   overflow: hidden;
   text-overflow: ellipsis;
 }
+
+html.dark .shiki,
+html.dark .shiki span {
+  color: var(--shiki-dark) !important;
+  background-color: var(--shiki-dark-bg) !important;
+  font-style: var(--shiki-dark-font-style) !important;
+  font-weight: var(--shiki-dark-font-weight) !important;
+  text-decoration: var(--shiki-dark-text-decoration) !important;
+}
diff --git a/docs/en/guide/getting-started.md b/docs/en/guide/getting-started.md
@@ -30,6 +30,7 @@ It will be exposed to global as `window.StarterLibVue3`
 ```vue
 <script setup>
 import { SayHello } from 'starter-lib-vue3'
+import 'starter-lib-vue3/style.css'
 </script>
 
 <template>
diff --git a/docs/examples/say-hello/basic.vue b/docs/examples/say-hello/basic.vue
@@ -1,5 +1,6 @@
 <script setup>
 import { SayHello } from 'starter-lib-vue3'
+import 'starter-lib-vue3/style.css'
 </script>
 
 <template>
diff --git a/docs/zh/components/say-hello.md b/docs/zh/components/say-hello.md
@@ -2,14 +2,10 @@
 
 一个使用 `starter-lib-vue3` 的演示组件。
 
-## 用法
+## 基本用法
 
-```vue
-<script setup>
-import { SayHello } from 'starter-lib-vue3'
-</script>
+::: example
 
-<template>
-  <SayHello name="Kieran" />
-</template>
-```
+say-hello/basic
+
+:::
diff --git a/docs/zh/guide/getting-started.md b/docs/zh/guide/getting-started.md
@@ -30,6 +30,7 @@ pnpm install starter-lib-vue3
 ```vue
 <script setup>
 import { SayHello } from 'starter-lib-vue3'
+import 'starter-lib-vue3/style.css'
 </script>
 
 <template>
diff --git a/package.json b/package.json
@@ -50,7 +50,7 @@
     "dev": "vite build --watch",
     "build": "pnpm clean && vite build",
     "docs:dev": "vitepress dev docs",
-    "docs:build": "vitepress build docs",
+    "docs:build": "pnpm build && vitepress build docs",
     "docs:preview": "vitepress preview docs",
     "test": "vitest",
     "lint": "eslint .",
diff --git a/src/components/SayHello.vue b/src/components/SayHello.vue
@@ -11,21 +11,21 @@ function sayHello() {
 
 <template>
   <button class="starter-lib-vue3-say-hello" @click="sayHello()">
-    Hi
+    Say, hi!
   </button>
 </template>
 
 <style>
 .starter-lib-vue3-say-hello{
-  background-color: #FF057C;
-  border: none;
+  background: #42b883;
   color: white;
-  padding: 15px 32px;
+  padding: 8px 20px;
   text-align: center;
   text-decoration: none;
   display: inline-block;
   font-size: 16px;
   margin: 4px 2px;
   cursor: pointer;
+  border-radius: 6px;
 }
 </style>
diff --git a/tsconfig.json b/tsconfig.json
@@ -6,18 +6,14 @@
     ],
     "module": "esnext",
     "moduleResolution": "node",
-    "paths": {
-      "starter-lib-vue3": [
-        "./src/index.ts"
-      ]
-    },
     "resolveJsonModule": true,
     "strict": true,
     "strictNullChecks": true,
     "esModuleInterop": true,
     "skipLibCheck": true
   },
   "include": [
-    "src/**/*.ts"
+    "src/**/*.ts",
+    "docs/**/*.ts"
   ]
 }
diff --git a/vite.config.ts b/vite.config.ts
@@ -32,37 +32,33 @@ export default defineConfig({
   // Vite Library mode, read more: https://vite.dev/guide/build.html#library-mode
   // https://vitejs.dev/config/#build-options
   build: {
-    emptyOutDir: false,
+    emptyOutDir: true,
     cssTarget: 'chrome61',
     minify: true,
     lib: {
       entry: 'src/index.ts',
+      name: 'StarterLibVue3',
+      formats: ['es', 'cjs', 'iife'],
+      fileName: (format) => {
+        if (format === 'es')
+          return `index.js`
+        if (format === 'cjs')
+          return `index.cjs`
+        if (format === 'iife')
+          return `index.global.js`
+        return `index.${format}.js`
+      },
       cssFileName: 'style',
     },
     rollupOptions: {
       external: [
         'vue',
       ],
-      input: 'src/index.ts',
-      output: [
-        {
-          format: 'es',
-          entryFileNames: 'index.js',
-          exports: 'named',
-          globals: {
-            vue: 'Vue',
-          },
+      output: {
+        globals: {
+          vue: 'Vue',
         },
-        {
-          format: 'cjs',
-          entryFileNames: 'index.cjs',
-        },
-        {
-          format: 'iife',
-          entryFileNames: 'index.global.js',
-          name: 'StarterLibVue3',
-        },
-      ],
+      },
     },
   },
 })
