ui-asciinema docs: ssr.noExternal motivation, Markdown use, global re…

…gistration (#402)
nolebase · Feb 9, 2025 · de62972 · de62972
1 parent b1f7e11
commit de62972
Show file tree

Hide file tree

Showing 3 changed files with 259 additions and 17 deletions.
diff --git a/docs/pages/en/ui/asciinema-player/index.md b/docs/pages/en/ui/asciinema-player/index.md
@@ -46,18 +46,21 @@ yarn add @nolebase/ui-asciinema
 
 ## Usage
 
-```js
+Add the package to Vite's `ssr.noExternal` configuration. Without this, your site may not build. (Ref: [Vite's `ssr.noExternal` config docs](https://vitejs.dev/guide/ssr.html#ssr-externals).)
+
+```ts
 // vite.config.ts
 export default defineConfig({
   ssr: {
     noExternal: [
-      // If there are other packages that need to be processed by Vite, you can add them here.
-      '@nolebase/ui-asciinema',
+      "@nolebase/ui-asciinema",
     ],
   },
 })
 ```
 
+Then import `NuAsciinemaPlayer` and asciinema-player's stylesheet in your Vue file. (Ref: [asciinema-player's styling docs](https://docs.asciinema.org/manual/player/quick-start/#npm-package).)
+
 ```vue
 <script setup>
 // somewhere.vue
@@ -79,6 +82,125 @@ import 'asciinema-player/dist/bundle/asciinema-player.css'
 </template>
 ```
 
+### VitePress
+
+Instead of configuring Vite's `ssr.noExternal` in a `vite.config.ts`, you can configure it in the VitePress `vite` config. (Ref: [VitePress's Vite configuration docs](https://vitepress.dev/reference/site-config#vite).)
+
+```ts
+// **/.vitepress/config.ts
+export default defineConfig({
+  vite: {
+    ssr: {
+      noExternal: [
+        "@nolebase/ui-asciinema",
+      ],
+    },
+  },
+})
+```
+
+If the component is only used by a few pages, it's recommended to explicitly import it and the asciinema-player stylesheet where they are used. This allows them to be properly code-split and only loaded when the relevant pages are shown:
+
+- Markdown
+
+    ```html
+    <script setup>
+    // somewhere.md
+    import { NuAsciinemaPlayer } from '@nolebase/ui-asciinema'
+    import 'asciinema-player/dist/bundle/asciinema-player.css'
+    </script>
+
+    <NuAsciinemaPlayer
+      src="/asciinema/test-nyancat.cast"
+      :preload="true"
+      :cols="400"
+      :rows="40"
+      :auto-play="true"
+      :controls="true"
+      :terminal-font-size="'12px'"
+      :loop="true"
+    />
+    ```
+
+- Vue
+
+    ```vue
+    <script setup>
+    // somewhere.vue
+    import { NuAsciinemaPlayer } from '@nolebase/ui-asciinema'
+    import 'asciinema-player/dist/bundle/asciinema-player.css'
+    </script>
+
+    <template>
+      <NuAsciinemaPlayer
+        src="/asciinema/test-nyancat.cast"
+        :preload="true"
+        :cols="400"
+        :rows="40"
+        :auto-play="true"
+        :controls="true"
+        :terminal-font-size="'12px'"
+        :loop="true"
+      />
+    </template>
+    ```
+
+If the component is going to be used on most of the pages, it and the asciinema-player stylesheet can be registered globally by customizing the VitePress Vue app instance.
+
+```ts
+// **/.vitepress/theme/index.ts
+import { NuAsciinemaPlayer } from "@nolebase/ui-asciinema";
+import "asciinema-player/dist/bundle/asciinema-player.css";
+
+export default {
+  enhanceApp({ app, router, siteData }) {
+    app.component("NuAsciinemaPlayer", NuAsciinemaPlayer);
+  }
+}
+```
+
+- Markdown
+
+    ```html
+    <!-- somewhere.md -->
+
+    <NuAsciinemaPlayer
+      src="/asciinema/test-nyancat.cast"
+      :preload="true"
+      :cols="400"
+      :rows="40"
+      :auto-play="true"
+      :controls="true"
+      :terminal-font-size="'12px'"
+      :loop="true"
+    />
+    ```
+
+- Vue
+
+    ```vue
+    <!-- somewhere.vue -->
+
+    <template>
+      <NuAsciinemaPlayer
+        src="/asciinema/test-nyancat.cast"
+        :preload="true"
+        :cols="400"
+        :rows="40"
+        :auto-play="true"
+        :controls="true"
+        :terminal-font-size="'12px'"
+        :loop="true"
+      />
+    </template>
+    ```
+
+Ref: [VitePress Registering Global Components docs](https://vitepress.dev/guide/extending-default-theme#registering-global-components).
+
+## Options
+
+Refer to [asciinema.d.ts](https://github.com/nolebase/integrations/blob/main/packages/ui-asciinema/src/asciinema.d.ts).
+
 ## Acknowledgements
 
 - [NARKOZ/go-nyancat: Nyancat in your terminal](https://github.com/NARKOZ/go-nyancat)

diff --git a/docs/pages/zh-CN/ui/asciinema-player/index.md b/docs/pages/zh-CN/ui/asciinema-player/index.md
@@ -46,18 +46,21 @@ yarn add @nolebase/ui-asciinema
 
 ## 用法
 
-```js
+Add the package to Vite's `ssr.noExternal` configuration. Without this, your site may not build. (Ref: [Vite's `ssr.noExternal` config docs](https://vitejs.dev/guide/ssr.html#ssr-externals).)
+
+```ts
 // vite.config.ts
 export default defineConfig({
   ssr: {
     noExternal: [
-      // If there are other packages that need to be processed by Vite, you can add them here.
-      '@nolebase/ui-asciinema',
+      "@nolebase/ui-asciinema",
     ],
   },
 })
 ```
 
+Then import `NuAsciinemaPlayer` and asciinema-player's stylesheet in your Vue file. (Ref: [asciinema-player's styling docs](https://docs.asciinema.org/manual/player/quick-start/#npm-package).)
+
 ```vue
 <script setup>
 // somewhere.vue
@@ -79,6 +82,125 @@ import 'asciinema-player/dist/bundle/asciinema-player.css'
 </template>
 ```
 
+### VitePress
+
+Instead of configuring Vite's `ssr.noExternal` in a `vite.config.ts`, you can configure it in the VitePress `vite` config. (Ref: [VitePress's Vite configuration docs](https://vitepress.dev/reference/site-config#vite).)
+
+```ts
+// **/.vitepress/config.ts
+export default defineConfig({
+  vite: {
+    ssr: {
+      noExternal: [
+        "@nolebase/ui-asciinema",
+      ],
+    },
+  },
+})
+```
+
+If the component is only used by a few pages, it's recommended to explicitly import it and the asciinema-player stylesheet where they are used. This allows them to be properly code-split and only loaded when the relevant pages are shown:
+
+- Markdown
+
+    ```html
+    <script setup>
+    // somewhere.md
+    import { NuAsciinemaPlayer } from '@nolebase/ui-asciinema'
+    import 'asciinema-player/dist/bundle/asciinema-player.css'
+    </script>
+
+    <NuAsciinemaPlayer
+      src="/asciinema/test-nyancat.cast"
+      :preload="true"
+      :cols="400"
+      :rows="40"
+      :auto-play="true"
+      :controls="true"
+      :terminal-font-size="'12px'"
+      :loop="true"
+    />
+    ```
+
+- Vue
+
+    ```vue
+    <script setup>
+    // somewhere.vue
+    import { NuAsciinemaPlayer } from '@nolebase/ui-asciinema'
+    import 'asciinema-player/dist/bundle/asciinema-player.css'
+    </script>
+
+    <template>
+      <NuAsciinemaPlayer
+        src="/asciinema/test-nyancat.cast"
+        :preload="true"
+        :cols="400"
+        :rows="40"
+        :auto-play="true"
+        :controls="true"
+        :terminal-font-size="'12px'"
+        :loop="true"
+      />
+    </template>
+    ```
+
+If the component is going to be used on most of the pages, it and the asciinema-player stylesheet can be registered globally by customizing the VitePress Vue app instance.
+
+```ts
+// **/.vitepress/theme/index.ts
+import { NuAsciinemaPlayer } from "@nolebase/ui-asciinema";
+import "asciinema-player/dist/bundle/asciinema-player.css";
+
+export default {
+  enhanceApp({ app, router, siteData }) {
+    app.component("NuAsciinemaPlayer", NuAsciinemaPlayer);
+  }
+}
+```
+
+- Markdown
+
+    ```html
+    <!-- somewhere.md -->
+
+    <NuAsciinemaPlayer
+      src="/asciinema/test-nyancat.cast"
+      :preload="true"
+      :cols="400"
+      :rows="40"
+      :auto-play="true"
+      :controls="true"
+      :terminal-font-size="'12px'"
+      :loop="true"
+    />
+    ```
+
+- Vue
+
+    ```vue
+    <!-- somewhere.vue -->
+
+    <template>
+      <NuAsciinemaPlayer
+        src="/asciinema/test-nyancat.cast"
+        :preload="true"
+        :cols="400"
+        :rows="40"
+        :auto-play="true"
+        :controls="true"
+        :terminal-font-size="'12px'"
+        :loop="true"
+      />
+    </template>
+    ```
+
+Ref: [VitePress Registering Global Components docs](https://vitepress.dev/guide/extending-default-theme#registering-global-components).
+
+## Options
+
+Refer to [asciinema.d.ts](https://github.com/nolebase/integrations/blob/main/packages/ui-asciinema/src/asciinema.d.ts).
+
 ## 致谢
 
 - [NARKOZ/go-nyancat: Nyancat in your terminal](https://github.com/NARKOZ/go-nyancat)

diff --git a/packages/ui-asciinema/README.md b/packages/ui-asciinema/README.md
@@ -10,24 +10,22 @@ Wrapper of `asciinema-player` for VitePress documentation sites.
 
 > [!IMPORTANT]
 >
-> ## For users who imported VitePress related components
->
-> If you are using VitePress, you will need to add the following configurations to your `vite.config.ts` file like this:
+> You will need to add the package to Vite's `ssr.noExternal` config [^1]. Without it your site may not build.
 >
 > ```typescript
-> export default defineConfig(() => {
->   return {
+> // vite.config.ts
+> export default defineConfig({
+>   vite: {
 >     ssr: {
 >       noExternal: [
->         // Add this line to your vite.config.ts
->         '@nolebase/ui-asciinema',
+>         "@nolebase/ui-asciinema",
 >       ],
 >     },
->   }
+>   },
 > })
 > ```
->
-> For more information about why configure this, please refer to the [Server-Side Rendering | Vite](https://vitejs.dev/guide/ssr.html#ssr-externals) documentation.
+
+[^1]: Vite's `ssr.noExternal` config docs: https://vitejs.dev/guide/ssr.html#ssr-externals.
 
 ## Install
 
@@ -51,4 +49,4 @@ pnpm add @nolebase/ui-asciinema -D
 
 ## Documentation
 
-Please refer to [Asciinema Player](https://nolebase-integrations.ayaka.io/pages/en/ui/asciinema-player/) for more information.
+Please refer to [Asciinema Player package's documentation site](https://nolebase-integrations.ayaka.io/pages/en/ui/asciinema-player/) for more information.