docs(protocol): add vidbee protocol docs (#150)

.github/workflows/translator.yaml

@@ -8,10 +8,6 @@ on:
     types: [created, edited]
   discussion_comment:
     types: [created, edited]
-  pull_request_target:
-    types: [opened, edited]
-  pull_request_review_comment:
-    types: [created, edited]
 
 jobs:
   translate:

docs/content/cookies.mdx

@@ -17,11 +17,13 @@ Cookies reuse your browser's signed-in session so VidBee can download content th
 
 In **Settings**, select your browser. VidBee will try to detect the browser profile path automatically. You can also enter the profile path manually.
 
+![Browser cookies settings](/browser-cookies.png)
+
 **Supported browsers (platform dependent):**
 
 - **Windows: Firefox only. Other browsers cannot be used for cookie reading.**
-- macOS: Safari, Chrome, Edge, Brave, Firefox, and more.
-- Linux: Chrome, Chromium, Brave, Firefox, and more.
+- macOS: All browsers supported.
+- Linux: All browsers supported.
 
 **Steps:**
 
@@ -36,6 +38,8 @@ On Windows, if you are not using Firefox, switch to the cookies file method.
 
 You can import a **Netscape-formatted** cookies file. This is useful when reading the browser profile is not possible.
 
+![Cookies file settings](/cookies-file.png)
+
 **Steps:**
 
 1. Export a Netscape cookies file using a browser extension.

docs/content/index.mdx

@@ -1,5 +1,5 @@
 ---
-title: VidBee Docs
+title: Introduction
 description: VidBee desktop downloader documentation and FAQ
 ---
 
@@ -9,6 +9,7 @@ These docs focus on real-world usage and settings, especially signed-in download
 
 ## Start here
 
+- [vidbee:// Protocol](./protocol.mdx): Quick download using URL protocol.
 - [Cookies](./cookies.mdx): Configure signed-in sessions and restricted content.
 - [FAQ](./faq.mdx): Common questions and troubleshooting.
 

docs/content/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "VidBee Docs",
-  "pages": ["index", "cookies", "faq"]
+  "pages": ["index", "protocol", "cookies", "faq"]
 }

docs/content/protocol.mdx

@@ -0,0 +1,149 @@
+---
+title: vidbee:// Protocol
+description: Quick download using vidbee:// URL protocol
+---
+
+VidBee registers a custom URL protocol (`vidbee://`) that allows you to trigger downloads directly from web browsers, browser extensions, or userscripts.
+
+## Basic Usage
+
+The `vidbee://` protocol can be used to open VidBee and automatically start downloading videos.
+
+### Protocol Format
+
+```
+vidbee://download?url=<encoded-video-url>
+```
+
+**Parameters:**
+- `url` (required): The video URL to download, must be URL-encoded
+
+### Example
+
+To download a YouTube video:
+
+```html
+<a href="vidbee://download?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ">
+  Download with VidBee
+</a>
+```
+
+Or in JavaScript:
+
+```javascript
+const videoUrl = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
+const vidbeeUrl = `vidbee://download?url=${encodeURIComponent(videoUrl)}`
+window.location.href = vidbeeUrl
+```
+
+## Opening VidBee
+
+To simply open the VidBee app without starting a download:
+
+```
+vidbee://
+```
+
+## Use Cases
+
+### Browser Extension
+
+The VidBee browser extension uses this protocol to send the current tab's URL to the desktop app:
+
+```javascript
+const currentUrl = window.location.href
+const deepLink = `vidbee://download?url=${encodeURIComponent(currentUrl)}`
+window.location.href = deepLink
+```
+
+### Userscript Integration
+
+The VidBee userscript adds quick download buttons to supported video sites:
+
+```javascript
+// Single click triggers download via protocol
+const vidbeeUrl = `vidbee://download?url=${encodeURIComponent(videoUrl)}`
+window.location.href = vidbeeUrl
+```
+
+### Web Pages
+
+You can add direct download links to your web pages:
+
+```html
+<!-- Simple link -->
+<a href="vidbee://download?url=https%3A%2F%2Fexample.com%2Fvideo">
+  Download with VidBee
+</a>
+
+<!-- Button with JavaScript -->
+<button onclick="openInVidBee('https://example.com/video')">
+  Quick Download
+</button>
+
+<script>
+function openInVidBee(url) {
+  const vidbeeUrl = `vidbee://download?url=${encodeURIComponent(url)}`
+  window.location.href = vidbeeUrl
+}
+</script>
+```
+
+## Playlist Support
+
+To download an entire playlist:
+
+```
+vidbee://download?url=<encoded-playlist-url>&type=playlist
+```
+
+**Parameters:**
+- `url` (required): The playlist URL, must be URL-encoded
+- `type`: Set to `playlist` to download all videos in the playlist
+
+### Example
+
+```javascript
+const playlistUrl = 'https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf'
+const vidbeeUrl = `vidbee://download?url=${encodeURIComponent(playlistUrl)}&type=playlist`
+window.location.href = vidbeeUrl
+```
+
+## How It Works
+
+1. **Protocol Registration**: VidBee registers as the handler for the `vidbee://` protocol during installation
+2. **URL Parsing**: When a `vidbee://download?url=...` link is clicked, the OS launches VidBee
+3. **Queue Processing**: VidBee extracts the video URL and adds it to the download queue
+4. **Auto-start**: The download begins automatically if the app is configured for auto-download
+
+## Browser Compatibility
+
+The `vidbee://` protocol works across all major browsers:
+- Chrome/Edge/Brave
+- Firefox
+- Safari
+
+## Security Notes
+
+- Only URLs starting with `vidbee://` will trigger the app
+- The app validates the URL format before processing
+- Malformed URLs are ignored with a warning in the logs
+
+## Troubleshooting
+
+### Protocol Not Working
+
+If clicking `vidbee://` links doesn't open VidBee:
+
+1. **Check installation**: Ensure VidBee is properly installed
+2. **Reinstall**: Try reinstalling VidBee to re-register the protocol
+3. **OS permissions**: On macOS, check System Settings > Privacy & Security for any blocks
+4. **Browser settings**: Some browsers may require you to allow the protocol on first use
+
+### App Opens But Doesn't Download
+
+If VidBee opens but the download doesn't start:
+
+1. **Check URL encoding**: Ensure the video URL is properly encoded with `encodeURIComponent()`
+2. **Check logs**: Open the app and check the developer console for errors
+3. **Supported sites**: Verify the URL is from a [supported site](https://vidbee.org/supported-sites/)

docs/content/zh/cookies.mdx

@@ -17,11 +17,13 @@ Cookie 用于复用浏览器的登录态，帮助 VidBee 下载需要登录或
 
 在 **设置** 中选择你的浏览器，VidBee 会尝试自动识别浏览器配置文件路径。你也可以手动填写配置文件路径。
 
+![浏览器 Cookie 设置](/browser-cookies.png)
+
 **支持的浏览器（按平台差异显示）：**
 
 - **Windows：仅支持 Firefox。其他浏览器无法读取 Cookie。**
-- macOS：Safari、Chrome、Edge、Brave、Firefox 等。
-- Linux：Chrome、Chromium、Brave、Firefox 等。
+- macOS：全部支持。
+- Linux：全部支持。
 
 **使用步骤：**
 
@@ -36,6 +38,8 @@ Cookie 用于复用浏览器的登录态，帮助 VidBee 下载需要登录或
 
 你也可以导入 **Netscape 格式** 的 cookies 文件。这个方式适合在不方便读取浏览器配置文件时使用。
 
+![Cookies 文件设置](/cookies-file.png)
+
 **使用步骤：**
 
 1. 使用浏览器扩展导出 Netscape cookies 文件。

docs/content/zh/index.mdx

@@ -1,5 +1,5 @@
 ---
-title: VidBee 文档
+title: 简介
 description: VidBee 桌面下载器使用说明与常见问题
 ---
 
@@ -9,6 +9,7 @@ VidBee 是一款基于 Electron 的桌面下载器，内置 yt-dlp 引擎，提
 
 ## 从这里开始
 
+- [vidbee:// 协议](./protocol.mdx)：使用 URL 协议快速下载。
 - [Cookie 使用](./cookies.mdx)：登录态与限制内容的下载配置。
 - [常见问题](./faq.mdx)：常见问题与排查思路。
 

docs/content/zh/meta.json

@@ -1,4 +1,4 @@
 {
   "title": "VidBee 文档",
-  "pages": ["index", "cookies", "faq"]
+  "pages": ["index", "protocol", "cookies", "faq"]
 }

docs/content/zh/protocol.mdx

@@ -0,0 +1,149 @@
+---
+title: vidbee:// 协议
+description: 使用 vidbee:// URL 协议快速下载
+---
+
+VidBee 注册了自定义 URL 协议（`vidbee://`），允许您直接从网页浏览器、浏览器扩展或用户脚本触发下载。
+
+## 基本用法
+
+`vidbee://` 协议可用于打开 VidBee 并自动开始下载视频。
+
+### 协议格式
+
+```
+vidbee://download?url=<编码后的视频URL>
+```
+
+**参数：**
+- `url`（必需）：要下载的视频 URL，必须经过 URL 编码
+
+### 示例
+
+下载 YouTube 视频：
+
+```html
+<a href="vidbee://download?url=https%3A%2F%2Fwww.youtube.com%2Fwatch%3Fv%3DdQw4w9WgXcQ">
+  使用 VidBee 下载
+</a>
+```
+
+或使用 JavaScript：
+
+```javascript
+const videoUrl = 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
+const vidbeeUrl = `vidbee://download?url=${encodeURIComponent(videoUrl)}`
+window.location.href = vidbeeUrl
+```
+
+## 打开 VidBee
+
+仅打开 VidBee 应用而不开始下载：
+
+```
+vidbee://
+```
+
+## 使用场景
+
+### 浏览器扩展
+
+VidBee 浏览器扩展使用此协议将当前标签页的 URL 发送到桌面应用：
+
+```javascript
+const currentUrl = window.location.href
+const deepLink = `vidbee://download?url=${encodeURIComponent(currentUrl)}`
+window.location.href = deepLink
+```
+
+### 用户脚本集成
+
+VidBee 用户脚本在支持的视频网站上添加快速下载按钮：
+
+```javascript
+// 单击通过协议触发下载
+const vidbeeUrl = `vidbee://download?url=${encodeURIComponent(videoUrl)}`
+window.location.href = vidbeeUrl
+```
+
+### 网页集成
+
+您可以在网页中添加直接下载链接：
+
+```html
+<!-- 简单链接 -->
+<a href="vidbee://download?url=https%3A%2F%2Fexample.com%2Fvideo">
+  使用 VidBee 下载
+</a>
+
+<!-- 带 JavaScript 的按钮 -->
+<button onclick="openInVidBee('https://example.com/video')">
+  快速下载
+</button>
+
+<script>
+function openInVidBee(url) {
+  const vidbeeUrl = `vidbee://download?url=${encodeURIComponent(url)}`
+  window.location.href = vidbeeUrl
+}
+</script>
+```
+
+## 播放列表支持
+
+下载整个播放列表：
+
+```
+vidbee://download?url=<编码后的播放列表URL>&type=playlist
+```
+
+**参数：**
+- `url`（必需）：播放列表 URL，必须经过 URL 编码
+- `type`：设置为 `playlist` 以下载播放列表中的所有视频
+
+### 示例
+
+```javascript
+const playlistUrl = 'https://www.youtube.com/playlist?list=PLrAXtmErZgOeiKm4sgNOknGvNjby9efdf'
+const vidbeeUrl = `vidbee://download?url=${encodeURIComponent(playlistUrl)}&type=playlist`
+window.location.href = vidbeeUrl
+```
+
+## 工作原理
+
+1. **协议注册**：VidBee 在安装过程中注册为 `vidbee://` 协议的处理程序
+2. **URL 解析**：当点击 `vidbee://download?url=...` 链接时，操作系统会启动 VidBee
+3. **队列处理**：VidBee 提取视频 URL 并将其添加到下载队列
+4. **自动开始**：如果应用配置为自动下载，下载会自动开始
+
+## 浏览器兼容性
+
+`vidbee://` 协议适用于所有主流浏览器：
+- Chrome/Edge/Brave
+- Firefox
+- Safari
+
+## 安全说明
+
+- 仅以 `vidbee://` 开头的 URL 会触发应用
+- 应用在处理前会验证 URL 格式
+- 格式错误的 URL 将被忽略，并在日志中显示警告
+
+## 故障排除
+
+### 协议不工作
+
+如果点击 `vidbee://` 链接无法打开 VidBee：
+
+1. **检查安装**：确保 VidBee 已正确安装
+2. **重新安装**：尝试重新安装 VidBee 以重新注册协议
+3. **操作系统权限**：在 macOS 上，检查系统设置 > 隐私与安全性 是否有任何阻止
+4. **浏览器设置**：某些浏览器可能需要您在首次使用时允许该协议
+
+### 应用打开但未下载
+
+如果 VidBee 打开但下载未开始：
+
+1. **检查 URL 编码**：确保视频 URL 使用 `encodeURIComponent()` 正确编码
+2. **检查日志**：打开应用并检查开发者控制台是否有错误
+3. **支持的网站**：验证 URL 是否来自[支持的网站](https://vidbee.org/supported-sites/)

docs/next.config.mjs

@@ -4,7 +4,8 @@ const withMDX = createMDX();
 
 /** @type {import('next').NextConfig} */
 const config = {
-  output: 'export',
+  // Only use static export for production builds, not dev mode
+  output: process.env.NODE_ENV === 'production' ? 'export' : undefined,
   reactStrictMode: true,
   // Use trailing slashes to avoid conflicts with route handlers that have file extensions
   trailingSlash: true,

docs/src/app/layout.tsx

@@ -1,12 +1,25 @@
 import './global.css';
 import { Inter } from 'next/font/google';
 import type { ReactNode } from 'react';
+import type { Metadata } from 'next';
 import { i18n, isLocale } from '@/lib/i18n';
 
 const inter = Inter({
   subsets: ['latin'],
 });
 
+export const metadata: Metadata = {
+  icons: {
+    icon: [
+      { url: '/favicon.png', sizes: '32x32', type: 'image/png' },
+      { url: '/icon-16.png', sizes: '16x16', type: 'image/png' },
+      { url: '/icon-32.png', sizes: '32x32', type: 'image/png' },
+      { url: '/icon-192.png', sizes: '192x192', type: 'image/png' },
+    ],
+    apple: '/apple-touch-icon.png',
+  },
+};
+
 export default async function Layout({
   children,
   params,