docs(ui): added detailed documentations for NuLazyTeleportRiveCanvas …

…with twoslash support Signed-off-by: Neko Ayaka <neko@ayaka.moe>
nolebase · Mar 28, 2024 · 263f7e0 · 263f7e0
1 parent e1dbef5
commit 263f7e0
Show file tree

Hide file tree

Showing 12 changed files with 1,207 additions and 122 deletions.
diff --git a/.vscode/settings.json b/.vscode/settings.json
@@ -12,14 +12,15 @@
     "iconify",
     "Logseq",
     "mkdist",
+    "Nisekoi5",
     "nolebase",
     "Nólëbase",
     "quotepath",
     "Rehype",
     "resvg",
+    "Twoslash",
     "unconfig",
-    "uncrypto",
-    "Nisekoi5"
+    "uncrypto"
   ],
   "editor.formatOnSave": false,
   "editor.codeActionsOnSave": {

diff --git a/docs/.vitepress/config.ts b/docs/.vitepress/config.ts
@@ -1,88 +1,163 @@
 import { cwd, env } from 'node:process'
 import { join, relative } from 'node:path'
 import { type DefaultTheme, defineConfig } from 'vitepress'
+import MarkdownItFootnote from 'markdown-it-footnote'
+
+import { transformerTwoslash } from '@shikijs/vitepress-twoslash'
 import { BiDirectionalLinks } from '@nolebase/markdown-it-bi-directional-links'
 import type { Options as ElementTransformOptions } from '@nolebase/markdown-it-element-transform'
 import { ElementTransform } from '@nolebase/markdown-it-element-transform'
 import { buildEndGenerateOpenGraphImages } from '@nolebase/vitepress-plugin-og-image'
 
 export const sidebars: Record<string, DefaultTheme.Sidebar> = {
-  'en': [
-    {
-      text: 'Introduction',
-      items: [
-        { text: 'Getting Started', link: '/pages/en/guide/getting-started' },
-      ],
-    },
-    {
-      text: 'Integrations',
-      items: [
-        { text: 'Overview', link: '/pages/en/integrations/' },
-      ],
-    },
-    {
-      text: 'Obsidian Plugins',
-      items: [
-        { text: 'UnoCSS', link: '/pages/en/integrations/obsidian-plugin-unocss/' },
-      ],
-    },
-    {
-      text: 'Markdown It Plugins',
-      items: [
-        { text: 'Bi-directional links', link: '/pages/en/integrations/markdown-it-bi-directional-links/' },
-        { text: 'Elements Transformation', link: '/pages/en/integrations/markdown-it-element-transform/' },
-      ],
-    },
-    {
-      text: 'VitePress Plugins',
-      items: [
-        { text: 'Enhanced Readabilities', link: '/pages/en/integrations/vitepress-plugin-enhanced-readabilities/' },
-        { text: 'Inline Links Previewing', link: '/pages/en/integrations/vitepress-plugin-inline-link-preview/' },
-        { text: 'Blinking highlight targeted heading', link: '/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/' },
-        { text: 'Changelog & File history', link: '/pages/en/integrations/vitepress-plugin-git-changelog/' },
-        { text: 'Page properties', link: '/pages/en/integrations/vitepress-plugin-page-properties/' },
-        { text: 'Previewing image (social media card) generation', link: '/pages/en/integrations/vitepress-plugin-og-image/' },
-      ],
-    },
-  ],
-  'zh-CN': [
-    {
-      text: '指南',
-      items: [
-        { text: '如何开始', link: '/pages/zh-CN/guide/getting-started' },
-      ],
-    },
-    {
-      text: '集成',
-      items: [
-        { text: '概览', link: '/pages/zh-CN/integrations/' },
-      ],
-    },
-    {
-      text: 'Obsidian 插件',
-      items: [
-        { text: 'UnoCSS', link: '/pages/zh-CN/integrations/obsidian-plugin-unocss/' },
-      ],
-    },
-    {
-      text: 'Markdown It 插件',
-      items: [
-        { text: '双向链接', link: '/pages/zh-CN/integrations/markdown-it-bi-directional-links/' },
-        { text: '元素转换', link: '/pages/zh-CN/integrations/markdown-it-element-transform/' },
-      ],
-    },
-    {
-      text: 'VitePress 插件',
-      items: [
-        { text: '阅读增强', link: '/pages/zh-CN/integrations/vitepress-plugin-enhanced-readabilities/' },
-        { text: '行内链接预览', link: '/pages/zh-CN/integrations/vitepress-plugin-inline-link-preview/' },
-        { text: '闪烁高亮当前的目标标题', link: '/pages/zh-CN/integrations/vitepress-plugin-highlight-targeted-heading/' },
-        { text: '变更日志 及 文件历史', link: '/pages/zh-CN/integrations/vitepress-plugin-git-changelog/' },
-        { text: '页面属性', link: '/pages/zh-CN/integrations/vitepress-plugin-page-properties/' },
-        { text: '预览图片（社交媒体卡片）图片生成', link: '/pages/zh-CN/integrations/vitepress-plugin-og-image/' },
-      ],
-    },
-  ],
+  'en': {
+    '/': [
+      {
+        text: 'Guides',
+        items: [
+          { text: 'Getting Started', link: '/pages/en/guide/getting-started' },
+        ],
+      },
+      {
+        text: 'Integrations',
+        items: [
+          { text: 'Overview', link: '/pages/en/integrations/' },
+        ],
+      },
+      {
+        text: 'UI Components',
+        items: [
+          { text: 'Overview', link: '/pages/en/ui/' },
+        ],
+      },
+    ],
+    '/pages/en/integrations/': [
+      {
+        text: 'Integrations',
+        items: [
+          { text: 'Overview', link: '/pages/en/integrations/' },
+        ],
+      },
+      {
+        text: 'Obsidian Plugins',
+        items: [
+          { text: 'UnoCSS', link: '/pages/en/integrations/obsidian-plugin-unocss/' },
+        ],
+      },
+      {
+        text: 'Markdown It Plugins',
+        items: [
+          { text: 'Bi-directional links', link: '/pages/en/integrations/markdown-it-bi-directional-links/' },
+          { text: 'Elements Transformation', link: '/pages/en/integrations/markdown-it-element-transform/' },
+        ],
+      },
+      {
+        text: 'VitePress Plugins',
+        items: [
+          { text: 'Enhanced Readabilities', link: '/pages/en/integrations/vitepress-plugin-enhanced-readabilities/' },
+          { text: 'Inline Links Previewing', link: '/pages/en/integrations/vitepress-plugin-inline-link-preview/' },
+          { text: 'Blinking highlight targeted heading', link: '/pages/en/integrations/vitepress-plugin-highlight-targeted-heading/' },
+          { text: 'Changelog & File history', link: '/pages/en/integrations/vitepress-plugin-git-changelog/' },
+          { text: 'Page properties', link: '/pages/en/integrations/vitepress-plugin-page-properties/' },
+          { text: 'Previewing image (social media card) generation', link: '/pages/en/integrations/vitepress-plugin-og-image/' },
+        ],
+      },
+    ],
+    '/pages/en/ui/': [
+      {
+        text: 'UI Components',
+        items: [
+          { text: 'Overview', link: '/pages/en/ui/' },
+        ],
+      },
+      {
+        text: 'Actions',
+        items: [
+          { text: 'Button', link: '/pages/en/ui/button/' },
+        ],
+      },
+      {
+        text: 'Animations',
+        items: [
+          { text: 'Rive Canvas (Lazy Teleport)', link: '/pages/en/ui/lazyteleportrivecanvas/' },
+        ],
+      },
+    ],
+  },
+  'zh-CN': {
+    '/': [
+      {
+        text: '指南',
+        items: [
+          { text: '如何开始', link: '/pages/zh-CN/guide/getting-started' },
+        ],
+      },
+      {
+        text: '集成',
+        items: [
+          { text: '概览', link: '/pages/zh-CN/integrations/' },
+        ],
+      },
+      {
+        text: 'UI 组件',
+        items: [
+          { text: '概览', link: '/pages/zh-CN/ui/' },
+        ],
+      },
+    ],
+    '/pages/zh-CN/integrations/': [
+      {
+        text: '集成',
+        items: [
+          { text: '概览', link: '/pages/zh-CN/integrations/' },
+        ],
+      },
+      {
+        text: 'Obsidian 插件',
+        items: [
+          { text: 'UnoCSS', link: '/pages/zh-CN/integrations/obsidian-plugin-unocss/' },
+        ],
+      },
+      {
+        text: 'Markdown It 插件',
+        items: [
+          { text: '双向链接', link: '/pages/zh-CN/integrations/markdown-it-bi-directional-links/' },
+          { text: '元素转换', link: '/pages/zh-CN/integrations/markdown-it-element-transform/' },
+        ],
+      },
+      {
+        text: 'VitePress 插件',
+        items: [
+          { text: '阅读增强', link: '/pages/zh-CN/integrations/vitepress-plugin-enhanced-readabilities/' },
+          { text: '行内链接预览', link: '/pages/zh-CN/integrations/vitepress-plugin-inline-link-preview/' },
+          { text: '闪烁高亮当前的目标标题', link: '/pages/zh-CN/integrations/vitepress-plugin-highlight-targeted-heading/' },
+          { text: '变更日志 及 文件历史', link: '/pages/zh-CN/integrations/vitepress-plugin-git-changelog/' },
+          { text: '页面属性', link: '/pages/zh-CN/integrations/vitepress-plugin-page-properties/' },
+          { text: '预览图片（社交媒体卡片）图片生成', link: '/pages/zh-CN/integrations/vitepress-plugin-og-image/' },
+        ],
+      },
+    ],
+    '/pages/zh-CN/ui/': [
+      {
+        text: 'UI 组件',
+        items: [
+          { text: '概览', link: '/pages/zh-CN/ui/' },
+        ],
+      },
+      {
+        text: '操作',
+        items: [
+          { text: '按钮', link: '/pages/zh-CN/ui/button/' },
+        ],
+      },
+      {
+        text: '动画',
+        items: [
+          { text: 'Rive Canvas（懒加载）', link: '/pages/zh-CN/ui/lazyteleportrivecanvas/' },
+        ],
+      },
+    ],
+  },
 }
 
 function getVueProdHydrationMismatchDetailsFlag() {
@@ -166,6 +241,7 @@ export default defineConfig({
   },
   markdown: {
     config(md) {
+      md.use(MarkdownItFootnote)
       md.use(BiDirectionalLinks({
         dir: cwd(),
       }))
@@ -194,6 +270,11 @@ export default defineConfig({
         } as ElementTransformOptions
       })())
     },
+    codeTransformers: [
+      transformerTwoslash({
+        errorRendering: 'hover',
+      }),
+    ],
   },
   async buildEnd(siteConfig) {
     await buildEndGenerateOpenGraphImages({

diff --git a/docs/.vitepress/theme/index.ts b/docs/.vitepress/theme/index.ts
@@ -1,4 +1,5 @@
-import { h } from 'vue'
+import { type Plugin, h } from 'vue'
+import TwoslashFloatingVue from '@shikijs/vitepress-twoslash/client'
 
 import { NuLazyTeleportRiveCanvas } from '@nolebase/ui'
 import { NolebasePluginSet, defineThemeUnconfig } from '@nolebase/unconfig-vitepress'
@@ -8,6 +9,8 @@ import HomeContent from './components/HomeContent.vue'
 
 import 'virtual:uno.css'
 
+import '@shikijs/vitepress-twoslash/style.css'
+
 import './styles/vars.css'
 import './styles/main.css'
 
@@ -24,6 +27,7 @@ export default defineThemeUnconfig({
   enhanceApp: ({ app }) => {
     app.component('IntegrationCard', IntegrationCard)
     app.component('HomeContent', HomeContent)
+    app.use(TwoslashFloatingVue as Plugin)
   },
   pluginSets: [
     NolebasePluginSet({

diff --git a/docs/.vitepress/theme/styles/main.css b/docs/.vitepress/theme/styles/main.css
@@ -19,3 +19,16 @@ html, body {
 .vp-doc a:hover {
   text-decoration: underline;
 }
+
+/* 脚注 */
+.footnotes > .footnotes-list {
+  margin-top: 32px;
+  opacity: 0.9;
+  font-size: 12px;
+  /* 确保脚注上的返回链接符号 ↩ 不会被 body 的 Emoji 字体覆盖渲染为 ↩️ */
+  font-family: sans-serif;
+}
+
+.footnotes > .footnotes-list > .footnote-item > p {
+  line-height: 18px;
+}
diff --git a/docs/package.json b/docs/package.json
@@ -19,6 +19,9 @@
     "@nolebase/vitepress-plugin-og-image": "workspace:^",
     "@nolebase/vitepress-plugin-page-properties": "workspace:^",
     "@rive-app/canvas": "^2.11.1",
-    "@rollup/plugin-yaml": "^4.1.2"
+    "@rollup/plugin-yaml": "^4.1.2",
+    "@shikijs/vitepress-twoslash": "^1.2.1",
+    "@types/markdown-it-footnote": "^3.0.4",
+    "markdown-it-footnote": "^4.0.0"
   }
 }
diff --git a/docs/pages/en/ui/button/index.md b/docs/pages/en/ui/button/index.md
@@ -0,0 +1,19 @@
+<script setup>
+import { NuButton } from '@nolebase/ui'
+</script>
+
+# Buttons <Badge type="danger" text="Alpha" />
+
+::: danger 🛑 This package is in Alpha stage.
+This package is still in the Alpha stage, and it is not recommended to use it in production. The API may change in the future, and there may be bugs in the current version. Please use it with caution.
+:::
+
+::: warning 🚧 Constructing
+Nice to meet you! But sorry, this page is still under construction. If you don’t find the information you are interested in, you can first find the content you are interested in in the navigation in the sidebar to start reading.
+:::
+
+<div>
+  <NuButton>
+    ABCD
+  </NuButton>
+</div>
diff --git a/docs/pages/en/ui/index.md b/docs/pages/en/ui/index.md
@@ -26,13 +26,15 @@ Therefore, if you would ever want to install `@nolebase/ui` as one of your depen
 
 Since `<NuLazyTeleportRiveCanvas />` depends on `@rive-app/canvas`. If you also use Vite as your bundler, you will need to add the following configurations to your `vite.config.ts` file like this:
 
-```typescript
+```typescript twoslash
+import { defineConfig } from 'vite'
+
 export default defineConfig(() => {
   return {
     optimizeDeps: { // [!code ++]
       include: [ // [!code ++]
         // Add this line to your vite.config.ts's optimizeDeps.include array // [!code ++]
-        '@nolebase/ui  @rive-app/canvas', // [!code ++]
+        '@nolebase/ui > @rive-app/canvas', // [!code ++]
       ], // [!code ++]
     }, // [!code ++]
   }
@@ -45,7 +47,9 @@ For more information about why configure this, please refer to the [Dep Optimiza
 
 If you are using VitePress, and imported components relies on VitePress, you will need to add the following configurations to your `vite.config.ts` file like this:
 
-```typescript
+```typescript twoslash
+import { defineConfig } from 'vite'
+
 export default defineConfig(() => {
   return {
     ssr: { // [!code ++]
@@ -81,11 +85,3 @@ yarn add @nolebase/ui -D
 ```
 
 :::
-
-## Buttons
-
-<div>
-  <NuButton>
-    ABCD
-  </NuButton>
-</div>