refactor(docs): use nextra + next

Aliorpse · Aliorpse · commit 8f2c2b0bc62b · 2026-03-20T01:28:34.000+08:00
diff --git a/.github/workflows/deploy-pages.yml b/.github/workflows/deploy-pages.yml
@@ -45,14 +45,14 @@ jobs:
       - name: Setup pages
         uses: actions/configure-pages@v5
 
-      - name: Build docs
+      - name: Build docs with Next.js
         working-directory: saltify-docs
         run: pnpm build
 
       - name: Upload Pages artifact
         uses: actions/upload-pages-artifact@v3
         with:
-          path: saltify-docs/.vitepress/dist
+          path: saltify-docs/out
 
   deploy:
     needs: build
diff --git a/saltify-docs/.gitignore b/saltify-docs/.gitignore
@@ -1 +1,7 @@
-.vitepress/cache
+# Next.js
+.next/
+out/
+*.tsbuildinfo
+
+# Dependencies
+node_modules/
diff --git a/saltify-docs/.vitepress/config.mts b/saltify-docs/.vitepress/config.mts
diff --git a/saltify-docs/app/[[...mdxPath]]/page.tsx b/saltify-docs/app/[[...mdxPath]]/page.tsx
@@ -0,0 +1,31 @@
+import { generateStaticParamsFor, importPage } from 'nextra/pages';
+import { useMDXComponents as getMDXComponents } from '../../mdx-components';
+import { Metadata } from 'next';
+
+export const generateStaticParams = generateStaticParamsFor('mdxPath');
+
+type Props = {
+  params: Promise<{ slug: string; mdxPath: string[] }>;
+  searchParams: Promise<{ [key: string]: string | string[] | undefined }>;
+};
+
+export async function generateMetadata(props: Props): Promise<Metadata> {
+  const params = await props.params;
+  const { metadata } = await importPage(params.mdxPath);
+  return {
+    ...metadata,
+    title: metadata.title ? `Saltify | ${metadata.title}` : 'Saltify 文档',
+  };
+}
+
+const Wrapper = getMDXComponents().wrapper;
+
+export default async function Page(props: Props) {
+  const params = await props.params;
+  const { default: MDXContent, toc, metadata } = await importPage(params.mdxPath);
+  return (
+    <Wrapper toc={toc} metadata={metadata}>
+      <MDXContent {...props} params={params} />
+    </Wrapper>
+  );
+}
diff --git a/saltify-docs/app/layout.tsx b/saltify-docs/app/layout.tsx
@@ -0,0 +1,63 @@
+import { Footer, LastUpdated, Layout, Navbar } from 'nextra-theme-docs';
+import { getPageMap } from 'nextra/page-map';
+import 'nextra-theme-docs/style.css';
+import './styles.css';
+import { Head, Search } from 'nextra/components';
+import { Metadata } from 'next';
+
+export const metadata: Metadata = {
+  title: 'Saltify 文档',
+  description: '跨平台、可扩展的 QQ Bot 框架 & Milky SDK',
+};
+
+export default async function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="zh" suppressHydrationWarning>
+    <Head />
+    <body>
+    <Layout
+      navbar={
+        <Navbar
+          logo={
+            <div style={{ fontSize: '1.15rem' }}>
+              <b>Saltify</b> 文档
+            </div>
+          }
+          projectLink={'https://github.com/SaltifyDev/saltify'}
+        ></Navbar>
+      }
+      pageMap={await getPageMap()}
+      docsRepositoryBase="https://github.com/SaltifyDev/saltify/tree/main/saltify-docs"
+      search={
+        <Search
+          placeholder="搜索内容..."
+          emptyResult="没有找到相关内容"
+          errorText="加载索引失败"
+          loading="加载中..."
+        />
+      }
+      editLink="在 GitHub 上编辑此页"
+      feedback={{
+        content: '有问题？提交反馈',
+        labels: 'documentation',
+      }}
+      lastUpdated={<LastUpdated locale="zh">最后更新于</LastUpdated>}
+      themeSwitch={{
+        dark: '暗色',
+        light: '亮色',
+        system: '跟随系统',
+      }}
+      toc={{
+        title: '目录',
+        backToTop: '返回顶部',
+      }}
+    >
+      {children}
+      <Footer>
+        © {new Date().getFullYear()} SaltifyDev. Licensed under MIT.
+      </Footer>
+    </Layout>
+    </body>
+    </html>
+  );
+}
diff --git a/saltify-docs/app/nextra.d.ts b/saltify-docs/app/nextra.d.ts
@@ -0,0 +1,3 @@
+declare module 'nextra' {
+  export * from 'nextra/types';
+}
diff --git a/saltify-docs/app/styles.css b/saltify-docs/app/styles.css
@@ -0,0 +1,7 @@
+code, kbd, samp, pre {
+    font-family: SFMono-Regular, "SF Mono", "JetBrains Mono", Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+}
+
+code.nextra-code {
+    font-size: 1em;
+}
diff --git a/saltify-docs/content/_meta.ts b/saltify-docs/content/_meta.ts
@@ -0,0 +1,6 @@
+import type { MetaRecord } from 'nextra';
+
+export default {
+  index: '快速开始',
+  'docs-core': 'saltify-core 文档',
+} satisfies MetaRecord;
diff --git a/saltify-docs/content/docs-core/_meta.ts b/saltify-docs/content/docs-core/_meta.ts
@@ -0,0 +1,8 @@
+import type { MetaRecord } from 'nextra';
+
+export default {
+  application: '应用配置',
+  plugin: '插件开发',
+  command: '指令开发',
+  logging: '日志实现',
+} satisfies MetaRecord;
diff --git a/saltify-docs/content/docs-core/application.md b/saltify-docs/content/docs-core/application.md
diff --git a/saltify-docs/content/docs-core/command.md b/saltify-docs/content/docs-core/command.md
@@ -30,7 +30,8 @@ onFailure 块是**解析**失败的处理，注意这里不是异常，而是指
 
 默认情况下，如果不定义这个块，会忽视所有解析错误，并对指令不做回复。
 
-> [!tip]
+> [!TIP]
+> 
 > 与 `on` 一样，command 在插件初始化块中也是可以，并且推荐使用的。不需要传 `client`。
 
 ## 上下文隔离
@@ -53,7 +54,8 @@ client.command("info") {
 }
 ```
 
-> [!tip]
+> [!NOTE]
+> 
 > `onGroupExecute` 和 `onPrivateExecute` 的优先级**高于** `onExecute`。如果群聊触发了指令且你定义了 `onGroupExecute`，那么 `onExecute` 中的兜底逻辑将**不会**被执行。
 
 ## 子指令
diff --git a/saltify-docs/content/docs-core/logging.md b/saltify-docs/content/docs-core/logging.md
@@ -61,5 +61,6 @@ val myPlugin = SaltifyPlugin("my-plugin", ::Config) { config ->
 
 此时 logger 的 name 分别为: `Saltify/plugin:$pluginName` 与 `Saltify/cmd:$commandName`。
 
-> [!tip]
+> [!TIP]
+> 
 > 对于匿名插件，Saltify 会生成 `Saltify/plugin:anonymous-XXXX` 作为 logger name。
diff --git a/saltify-docs/content/docs-core/plugin.md b/saltify-docs/content/docs-core/plugin.md
@@ -37,7 +37,8 @@ val myPlugin = SaltifyPlugin("my-awesome-plugin", ::MyPluginConfig) { config ->
 }
 ```
 
-> [!tip]
+> [!TIP]
+> 
 > 所有 `respond` 函数都有一个为纯文本情况提供的简写形式。如上例，完全可以写成 `event.respond(config.reply)`。
 
 
diff --git a/saltify-docs/content/index.md b/saltify-docs/content/index.md
@@ -1,19 +1,35 @@
----
-layout: home
-
-hero:
-  name: Saltify
-  tagline: 跨平台、可扩展的 QQ Bot 框架 & Milky SDK
-  actions:
-    - theme: brand
-      text: 快速开始
-      link: /quick-tour
-
-features:
-  - title: 现代化基础设施
-    details: 基于 Kotlinx 全家桶实现，高效稳定
-  - title: 跨平台支持
-    details: 兼容 Kotlin JVM / Native / JS / Wasm 平台，一套代码覆盖更多运行环境
-  - title: 丰富功能
-    details: 支持 Milky 协议所有 API / 事件，支持插件化开发、指令路由、事件监听等 DSL
----
+# 快速开始
+
+欢迎来到 Saltify 的文档！
+
+Saltify 是一个跨平台、可扩展的 Kotlin QQ Bot 框架 & Milky SDK。
+
+- **现代化基础设施** - 基于 Kotlinx 全家桶实现，高效稳定
+- **跨平台支持** - 兼容 Kotlin JVM / Native / JS / Wasm 平台，一套代码覆盖更多运行环境
+- **丰富功能** - 支持 Milky 协议所有 API / 事件，支持插件化开发、指令路由、事件监听等 DSL
+
+## 开始之前
+
+### 添加 `saltify-core` 依赖
+
+[![Maven Central](https://img.shields.io/maven-central/v/org.ntqqrev/saltify-core?label=Maven%20Central&logo=maven)](https://central.sonatype.com/artifact/org.ntqqrev/saltify-core)
+
+对于使用 Gradle 的 Kotlin 项目，可以在 `build.gradle.kts` 中添加以下内容：
+
+```kotlin
+dependencies {
+    implementation("org.ntqqrev:saltify-core:$saltifyVersion")
+
+    // 你可以选择为 Ktor client 使用不同的引擎而不是 cio，这里只是一个推荐。
+    implementation("io.ktor:ktor-client-cio:$ktorVersion")
+
+    // 日志相关实现。同样，可以选择你所需要的平台日志实现。
+    implementation("ch.qos.logback:logback-classic:$logbackVersion")
+}
+```
+
+> [!IMPORTANT]
+> 
+> 本项目仍处于开发阶段，**强烈建议自行构建项目并依赖你的本地构建**，目前本文档将基于最新提交而不是最新发行版。待项目稳定会区分稳定文档与开发文档。
+
+在完成了以上配置后，点击页面下方的按钮，了解如何使用 Saltify 构建应用！
diff --git a/saltify-docs/content/quick-tour.md b/saltify-docs/content/quick-tour.md
diff --git a/saltify-docs/mdx-components.js b/saltify-docs/mdx-components.js
@@ -0,0 +1 @@
+export { useMDXComponents } from 'nextra-theme-docs';
diff --git a/saltify-docs/next-env.d.ts b/saltify-docs/next-env.d.ts
@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/dev/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.
diff --git a/saltify-docs/next.config.ts b/saltify-docs/next.config.ts
@@ -0,0 +1,18 @@
+import type { NextConfig } from 'next';
+import nextra from 'nextra';
+
+const withNextra = nextra({
+  whiteListTagsStyling: ['h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'p', 'a', 'code', 'pre'],
+});
+
+const nextConfig: NextConfig = {
+  output: 'export',
+  images: {
+    unoptimized: true,
+  },
+  typescript: {
+    ignoreBuildErrors: true,
+  }
+};
+
+export default withNextra(nextConfig);
diff --git a/saltify-docs/package.json b/saltify-docs/package.json
@@ -1,20 +1,35 @@
 {
   "name": "@saltify/docs",
-  "private": true,
   "version": "1.0.0",
-  "description": "",
+  "description": "Saltify Documentation",
   "main": "index.js",
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1",
-    "dev": "vitepress dev",
-    "build": "vitepress build",
-    "preview": "vitepress preview"
+    "dev": "next",
+    "build": "next build",
+    "start": "next start",
+    "postbuild": "pagefind --site .next/server/app --output-path out/_pagefind"
   },
   "keywords": [],
   "author": "",
   "license": "MIT",
   "packageManager": "pnpm@10.30.1",
+  "dependencies": {
+    "@theguild/remark-mermaid": "^0.3.0",
+    "next": "^16.1.6",
+    "nextra": "^4.6.1",
+    "nextra-theme-docs": "^4.6.1",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4"
+  },
   "devDependencies": {
-    "vitepress": "2.0.0-alpha.16"
+    "@eslint/eslintrc": "^3.3.3",
+    "@next/eslint-plugin-next": "^16.1.6",
+    "@types/node": "^25.2.3",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "eslint-config-next": "16.1.6",
+    "eslint-plugin-react-hooks": "^7.0.1",
+    "pagefind": "^1.4.0",
+    "typescript": "5.9.3"
   }
-}
+}
diff --git a/saltify-docs/pnpm-lock.yaml b/saltify-docs/pnpm-lock.yaml
diff --git a/saltify-docs/public/saltify-150.png b/saltify-docs/public/saltify-150.png
diff --git a/saltify-docs/public/saltify.png b/saltify-docs/public/saltify.png
diff --git a/saltify-docs/tsconfig.json b/saltify-docs/tsconfig.json

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+declare module 'nextra' {`
	`2`	`+ export * from 'nextra/types';`
	`3`	`+}`