docs: improve website (i18n/seo) + install demo video

README.md

@@ -10,6 +10,8 @@
   <p align="center">
     <a href="https://bvm-core.pages.dev"><strong>Official Website & Documentation »</strong></a>
     <br />
+    <a href="https://bvm-core.pages.dev/zh/"><strong>中文网站 »</strong></a>
+    <br />
     <br />
     <a href="./README.zh-CN.md">🇨🇳 中文文档</a>
     ·
@@ -49,7 +51,7 @@ irm https://bvm-core.pages.dev/install | iex
 
 ### Method 3: NPM (Optional)
 ```bash
-npm install -g bvm-core@latest
+npm install -g bvm-core@latest --foreground-scripts
 ```
 
 ---
@@ -102,6 +104,13 @@ echo "1.1.0" > .bvmrc
 
 ---
 
+## Troubleshooting
+
+- **Global tools are not isolated after switching versions**: run `bvm setup`, restart your terminal, and make sure `which bun` points to `~/.bvm/shims/bun` (macOS/Linux). On Windows, use `where.exe bun` and ensure `...\\.bvm\\shims\\bun.cmd` is first.
+- **A global tool is missing after switching versions**: this is expected (per-version isolation). Reinstall it under the active Bun version.
+
+---
+
 ## Design Philosophy
 
 ### ArchSense (Self-Bootstrapping)
@@ -114,4 +123,4 @@ Unlike managers that only switch the `PATH`, BVM performs **Filesystem-level Loc
 
 ## License
 
-MIT © [EricLLLLLL](https://github.com/EricLLLLLL)
+MIT © [EricLLLLLL](https://github.com/EricLLLLLL)

README.zh-CN.md

@@ -10,6 +10,8 @@
   <p align="center">
     <a href="https://bvm-core.pages.dev"><strong>官方网站与文档 »</strong></a>
     <br />
+    <a href="https://bvm-core.pages.dev/"><strong>English Site »</strong></a>
+    <br />
     <br />
     <a href="./README.md">🇺🇸 English Docs</a>
     ·
@@ -49,7 +51,7 @@ irm https://bvm-core.pages.dev/install | iex
 
 ### 方式 3: NPM (可选)
 ```bash
-npm install -g bvm-core@latest
+npm install -g bvm-core@latest --foreground-scripts
 ```
 
 ---
@@ -112,6 +114,13 @@ BVM 不分发沉重的预编译二进制文件。相反，它利用 **Bun 管理
 
 ---
 
+## 排障
+
+- **切换版本后还存在 pm2/cowsay 等全局命令**：先执行 `bvm setup`，重启终端，再检查 `which bun`（macOS/Linux）是否指向 `~/.bvm/shims/bun`；Windows 用 `where.exe bun` 并确保 `...\\.bvm\\shims\\bun.cmd` 排第一。
+- **切换版本后找不到某个全局命令**：这是预期行为（按版本隔离），请在当前版本下重新 `bun install -g <pkg>`。
+
+---
+
 ## 开源协议
 
-MIT © [EricLLLLLL](https://github.com/EricLLLLLL)
+MIT © [EricLLLLLL](https://github.com/EricLLLLLL)

website/docs/.vitepress/config.ts

@@ -1,41 +1,81 @@
-import { defineConfig } from 'vitepress'
+import { defineConfig } from 'vitepress';
+
+const SITE_URL = 'https://bvm-core.pages.dev';
 
 export default defineConfig({
-  title: "BVM",
-  description: "Bun Version Manager",
   head: [
-    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/logo.svg' }]
+    ['meta', { name: 'viewport', content: 'width=device-width,initial-scale=1' }],
+    ['link', { rel: 'icon', type: 'image/svg+xml', href: '/logo.svg' }],
+    ['meta', { property: 'og:site_name', content: 'BVM' }],
+    ['meta', { property: 'og:type', content: 'website' }],
+    ['meta', { property: 'og:image', content: `${SITE_URL}/logo.svg` }],
+    ['meta', { name: 'twitter:card', content: 'summary' }],
+    ['meta', { name: 'twitter:image', content: `${SITE_URL}/logo.svg` }],
   ],
-  themeConfig: {
-    logo: '/logo.svg',
-    nav: [
-      { text: 'Guide', link: '/guide/getting-started' },
-      { text: 'Architecture', link: '/guide/architecture' },
-      {
-        text: 'Author',
-        items: [
-          { text: '掘金 (Juejin)', link: 'https://juejin.cn/user/4072246800548999/posts' },
-          { text: '公众号 (WeChat)', link: 'https://mp.weixin.qq.com/s/CbO2wybwglEg6D5dh-tSCg' }
-        ]
+  cleanUrls: true,
+  lastUpdated: true,
+  locales: {
+    root: {
+      label: 'English',
+      lang: 'en-US',
+      title: 'BVM',
+      description: 'Bun Version Manager',
+      themeConfig: {
+        logo: '/logo.svg',
+        nav: [
+          { text: 'Guide', link: '/guide/getting-started' },
+          { text: 'Troubleshooting', link: '/guide/troubleshooting' },
+          { text: 'Architecture (CN)', link: '/guide/architecture' },
+          { text: '中文', link: '/zh/' },
+          { text: 'GitHub', link: 'https://github.com/EricLLLLLL/bvm' },
+        ],
+        sidebar: [
+          {
+            text: 'Guide',
+            items: [
+              { text: 'Getting Started', link: '/guide/getting-started' },
+              { text: 'Troubleshooting', link: '/guide/troubleshooting' },
+              { text: 'Architecture (CN)', link: '/guide/architecture' },
+            ],
+          },
+        ],
+        socialLinks: [{ icon: 'github', link: 'https://github.com/EricLLLLLL/bvm' }],
+        footer: {
+          message: 'Released under the MIT License.',
+          copyright: 'Copyright © 2024-present EricLLLLLL',
+        },
+      },
+    },
+    zh: {
+      label: '简体中文',
+      lang: 'zh-CN',
+      title: 'BVM',
+      description: 'Bun 版本管理器',
+      themeConfig: {
+        logo: '/logo.svg',
+        nav: [
+          { text: '指南', link: '/zh/guide/getting-started' },
+          { text: '排障', link: '/zh/guide/troubleshooting' },
+          { text: '架构', link: '/zh/guide/architecture' },
+          { text: 'English', link: '/' },
+          { text: 'GitHub', link: 'https://github.com/EricLLLLLL/bvm' },
+        ],
+        sidebar: [
+          {
+            text: '指南',
+            items: [
+              { text: '快速开始', link: '/zh/guide/getting-started' },
+              { text: '排障', link: '/zh/guide/troubleshooting' },
+              { text: '架构', link: '/zh/guide/architecture' },
+            ],
+          },
+        ],
+        socialLinks: [{ icon: 'github', link: 'https://github.com/EricLLLLLL/bvm' }],
+        footer: {
+          message: '基于 MIT License 发布。',
+          copyright: 'Copyright © 2024-present EricLLLLLL',
+        },
       },
-      { text: 'GitHub', link: 'https://github.com/EricLLLLLL/bvm' }
-    ],
-    sidebar: [
-      {
-        text: 'Introduction',
-        items: [
-          { text: 'Getting Started', link: '/guide/getting-started' },
-          { text: '快速开始 (CN)', link: '/guide/getting-started-zh' },
-          { text: 'Architecture', link: '/guide/architecture' }
-        ]
-      }
-    ],
-    socialLinks: [
-      { icon: 'github', link: 'https://github.com/EricLLLLLL/bvm' }
-    ],
-    footer: {
-      message: 'Released under the MIT License.',
-      copyright: 'Copyright © 2024-present EricLLLLLL'
-    }
-  }
-})
+    },
+  },
+});

website/docs/guide/getting-started-zh.md

@@ -10,6 +10,8 @@
   <p align="center">
     <a href="https://bvm-core.pages.dev"><strong>官方网站与文档 »</strong></a>
     <br />
+    <a href="https://bvm-core.pages.dev/"><strong>English Site »</strong></a>
+    <br />
     <br />
     <a href="./README.md">🇺🇸 English Docs</a>
     ·
@@ -49,7 +51,7 @@ irm https://bvm-core.pages.dev/install | iex
 
 ### 方式 3: NPM (可选)
 ```bash
-npm install -g bvm-core@latest
+npm install -g bvm-core@latest --foreground-scripts
 ```
 
 ---
@@ -112,6 +114,13 @@ BVM 不分发沉重的预编译二进制文件。相反，它利用 **Bun 管理
 
 ---
 
+## 排障
+
+- **切换版本后还存在 pm2/cowsay 等全局命令**：先执行 `bvm setup`，重启终端，再检查 `which bun`（macOS/Linux）是否指向 `~/.bvm/shims/bun`；Windows 用 `where.exe bun` 并确保 `...\\.bvm\\shims\\bun.cmd` 排第一。
+- **切换版本后找不到某个全局命令**：这是预期行为（按版本隔离），请在当前版本下重新 `bun install -g <pkg>`。
+
+---
+
 ## 开源协议
 
-MIT © [EricLLLLLL](https://github.com/EricLLLLLL)
+MIT © [EricLLLLLL](https://github.com/EricLLLLLL)

website/docs/guide/getting-started.md

@@ -10,6 +10,8 @@
   <p align="center">
     <a href="https://bvm-core.pages.dev"><strong>Official Website & Documentation »</strong></a>
     <br />
+    <a href="https://bvm-core.pages.dev/zh/"><strong>中文网站 »</strong></a>
+    <br />
     <br />
     <a href="./README.zh-CN.md">🇨🇳 中文文档</a>
     ·
@@ -49,7 +51,7 @@ irm https://bvm-core.pages.dev/install | iex
 
 ### Method 3: NPM (Optional)
 ```bash
-npm install -g bvm-core@latest
+npm install -g bvm-core@latest --foreground-scripts
 ```
 
 ---
@@ -102,6 +104,13 @@ echo "1.1.0" > .bvmrc
 
 ---
 
+## Troubleshooting
+
+- **Global tools are not isolated after switching versions**: run `bvm setup`, restart your terminal, and make sure `which bun` points to `~/.bvm/shims/bun` (macOS/Linux). On Windows, use `where.exe bun` and ensure `...\\.bvm\\shims\\bun.cmd` is first.
+- **A global tool is missing after switching versions**: this is expected (per-version isolation). Reinstall it under the active Bun version.
+
+---
+
 ## Design Philosophy
 
 ### ArchSense (Self-Bootstrapping)
@@ -114,4 +123,4 @@ Unlike managers that only switch the `PATH`, BVM performs **Filesystem-level Loc
 
 ## License
 
-MIT © [EricLLLLLL](https://github.com/EricLLLLLL)
+MIT © [EricLLLLLL](https://github.com/EricLLLLLL)

website/docs/guide/troubleshooting.md

@@ -0,0 +1,69 @@
+# Troubleshooting
+
+## 1) Global installs are not isolated (tools appear after switching versions)
+
+If `bun install -g` creates or uses `~/.bun`, it usually means your shell is not picking up **BVM shims first**.
+
+### Fix
+
+1. Run:
+
+```bash
+bvm setup
+```
+
+2. Restart your terminal (or reload your shell config).
+
+3. Verify:
+
+```bash
+which bun
+```
+
+Expected: it should point to `~/.bvm/shims/bun` (macOS/Linux).
+
+## 2) On Windows, `which` is not available
+
+Use PowerShell built-ins:
+
+```powershell
+Get-Command bun
+Get-Command cowsay
+where.exe bun
+where.exe cowsay
+```
+
+Expected: `where.exe bun` should list `...\.bvm\shims\bun.cmd` before `...\.bvm\current\bin\bun.exe`.
+
+## 3) I installed a global tool but it is not found
+
+BVM isolates global tools **per Bun version**. After switching versions, a global tool may be missing by design.
+
+### What to do
+
+- Reinstall it under the active version:
+
+```bash
+bun install -g <pkg>
+```
+
+- If your shell caches commands, refresh it:
+  - macOS/Linux: open a new terminal, or run `hash -r`
+  - Windows PowerShell: open a new PowerShell
+
+If needed, you can manually regenerate shims:
+
+```bash
+bvm rehash
+```
+
+## 4) PowerShell script execution is blocked
+
+If `install.ps1` fails due to policy restrictions, run this in PowerShell:
+
+```powershell
+Set-ExecutionPolicy -Scope CurrentUser -ExecutionPolicy RemoteSigned
+```
+
+Then retry the installer.
+

website/docs/index.md

@@ -12,6 +12,9 @@ hero:
     - theme: brand
       text: Get Started
       link: /guide/getting-started
+    - theme: alt
+      text: 中文
+      link: /zh/
     - theme: alt
       text: View on GitHub
       link: https://github.com/EricLLLLLL/bvm
@@ -83,6 +86,11 @@ const copy = (text, type) => {
   </div>
 </div>
 
+<div class="demo-section">
+  <h2>Install methods (animated)</h2>
+  <video class="demo-video" controls playsinline preload="metadata" src="/media/bvm-install-methods.mp4"></video>
+</div>
+
 <style>
 .install-section {
   margin-top: 4rem;
@@ -177,4 +185,20 @@ const copy = (text, type) => {
 .badge.alternative {
   background: var(--vp-c-text-3);
 }
-</style>
+
+.demo-section {
+  margin-top: 3.5rem;
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  gap: 1rem;
+}
+
+.demo-video {
+  width: 100%;
+  max-width: 900px;
+  border-radius: 12px;
+  border: 1px solid var(--vp-c-divider);
+  background: #000;
+}
+</style>

website/docs/public/robots.txt

@@ -0,0 +1,3 @@
+User-agent: *
+Allow: /
+

website/docs/zh/guide/architecture.md

@@ -0,0 +1,8 @@
+# BVM 架构与流程文档
+
+> **定位**: 本文档是 BVM 内部架构、安装流程和发布机制的单一真实来源。它既设计为供 AI 代理阅读（作为 Knowledge Base），也供人类贡献者参考。
+
+本页与 `/guide/architecture` 内容一致，专门提供在中文站点 `/zh/` 下的稳定路径，便于中英文同域部署与语言切换。
+
+- 继续阅读：请访问 `/guide/architecture`
+