docs: 迁移到 Astro Starlight 生成文档

all: 修正类型

.github/workflows/deploy-docs.yaml

@@ -38,4 +38,4 @@ jobs:
         uses: peaceiris/actions-gh-pages@v3
         with:
           github_token: ${{ secrets.GITHUB_TOKEN }}
-          publish_dir: packages/docs/out
+          publish_dir: packages/docs/dist

packages/core/src/lyric-player/dom/index.ts

@@ -8,7 +8,7 @@ import type { LyricLine } from "../../interfaces.ts";
 import "../../styles/index.css";
 import styles from "../../styles/lyric-player.module.css";
 import { debounce } from "../../utils/debounce.js";
-import { LyricPlayerBase } from "../base.ts";
+import { type LyricLineBase, LyricPlayerBase } from "../base.ts";
 import { LyricLineEl, type RawLyricLineMouseEvent } from "./lyric-line.ts";
 
 /**
@@ -23,7 +23,7 @@ export class LyricLineMouseEvent extends MouseEvent {
 		/**
 		 * 歌词行元素
 		 */
-		public readonly line: LyricLineEl,
+		public readonly line: LyricLineBase,
 		event: MouseEvent,
 	) {
 		super(`line-${event.type}`, event);

packages/core/src/lyric-player/index.ts

@@ -5,7 +5,9 @@ export * from "./canvas/index.ts";
 export * from "./dom-slim/index.ts";
 export * from "./dom/index.ts";
 
-/**
- * 默认导出的歌词播放组件
- */
-export const LyricPlayer = DomLyricPlayer;
+export {
+	/**
+	 * 默认导出的歌词播放组件
+	 */
+	DomLyricPlayer as LyricPlayer,
+};

packages/core/src/test.ts

@@ -5,14 +5,15 @@
  * @author SteveXMH
  */
 
+import * as lyrics from "@applemusic-like-lyrics/lyric";
 import {
 	type LyricLine as RawLyricLine,
 	parseLrc,
 	parseLys,
 	parseQrc,
+	parseTTML,
 	parseYrc,
 } from "@applemusic-like-lyrics/lyric";
-import { parseTTML } from "@applemusic-like-lyrics/ttml";
 import GUI from "lil-gui";
 import Stats from "stats.js";
 import type { LyricLine } from ".";
@@ -28,6 +29,8 @@ import {
 } from "./lyric-player";
 import type { SpringParams } from "./utils/spring";
 
+(window as any).lyrics = lyrics;
+
 const audio = document.createElement("audio");
 audio.volume = 0.5;
 audio.preload = "auto";
@@ -126,7 +129,7 @@ gui
 	.name("歌词文件")
 	.onFinishChange(async (url: string) => {
 		lyricPlayer.setLyricLines(
-			parseTTML(await (await fetch(url)).text()).lyricLines,
+			parseTTML(await (await fetch(url)).text()).lines.map(mapTTMLLyric),
 		);
 	});
 gui
@@ -274,16 +277,16 @@ declare global {
 	}
 }
 
-window.globalLyricPlayer = lyricPlayer;
+(window as any).globalLyricPlayer = lyricPlayer;
 
-const waitFrame = (): Promise<void> =>
+const waitFrame = (): Promise<number> =>
 	new Promise((resolve) => requestAnimationFrame(resolve));
 const mapLyric = (
 	line: RawLyricLine,
 	_i: number,
 	_lines: RawLyricLine[],
 ): LyricLine => ({
-	words: line.words,
+	words: line.words.map((word) => ({ obscene: false, ...word })),
 	startTime: line.words[0]?.startTime ?? 0,
 	endTime:
 		line.words[line.words.length - 1]?.endTime ?? Number.POSITIVE_INFINITY,
@@ -293,11 +296,16 @@ const mapLyric = (
 	isDuet: false,
 });
 
+const mapTTMLLyric = (line: RawLyricLine): LyricLine => ({
+	...line,
+	words: line.words.map((word) => ({ obscene: false, ...word })),
+});
+
 async function loadLyric() {
 	const lyricFile = debugValues.lyric;
 	const content = await (await fetch(lyricFile)).text();
 	if (lyricFile.endsWith(".ttml")) {
-		lyricPlayer.setLyricLines(parseTTML(content).lyricLines);
+		lyricPlayer.setLyricLines(parseTTML(content).lines.map(mapTTMLLyric));
 	} else if (lyricFile.endsWith(".lrc")) {
 		lyricPlayer.setLyricLines(parseLrc(content).map(mapLyric));
 	} else if (lyricFile.endsWith(".yrc")) {

packages/docs/.gitignore

@@ -1,36 +1,21 @@
-# See https://help.github.com/articles/ignoring-files/ for more about ignoring files.
+# build output
+dist/
+# generated types
+.astro/
 
 # dependencies
-/node_modules
-/.pnp
-.pnp.js
-.yarn/install-state.gz
+node_modules/
 
-# testing
-/coverage
-
-# next.js
-/.next/
-/out/
-
-# production
-/build
-
-# misc
-.DS_Store
-*.pem
-
-# debug
+# logs
 npm-debug.log*
 yarn-debug.log*
 yarn-error.log*
+pnpm-debug.log*
 
-# local env files
-.env*.local
 
-# vercel
-.vercel
+# environment variables
+.env
+.env.production
 
-# typescript
-*.tsbuildinfo
-next-env.d.ts
+# macOS-specific files
+.DS_Store

packages/docs/.vscode/extensions.json

@@ -0,0 +1,4 @@
+{
+  "recommendations": ["astro-build.astro-vscode"],
+  "unwantedRecommendations": []
+}

packages/docs/.vscode/launch.json

@@ -0,0 +1,11 @@
+{
+  "version": "0.2.0",
+  "configurations": [
+    {
+      "command": "./node_modules/.bin/astro dev",
+      "name": "Development server",
+      "request": "launch",
+      "type": "node-terminal"
+    }
+  ]
+}

packages/docs/README.md

@@ -1,5 +1,5 @@
 # AMLL Docs
 
-AMLL 框架的开发文档页面，使用 Next.js + MDX 编写并部署到 Github Pages。
+AMLL 框架的开发文档页面，使用 Astro + React + MDX 编写并部署到 Github Pages。
 
 [查看文档](https://steve-xmh.github.io/applemusic-like-lyrics/zh-CN)

packages/docs/astro.config.mjs

@@ -0,0 +1,122 @@
+// @ts-check
+import starlight from "@astrojs/starlight";
+import { defineConfig } from "astro/config";
+import { createStarlightTypeDocPlugin } from "starlight-typedoc";
+
+const [coreStarlightTypeDoc, coreTypeDocSidebarGroup] =
+	createStarlightTypeDocPlugin();
+const [reactStarlightTypeDoc, reactTypeDocSidebarGroup] =
+	createStarlightTypeDocPlugin();
+const [vueStarlightTypeDoc, vueTypeDocSidebarGroup] =
+	createStarlightTypeDocPlugin();
+const [reactFullStarlightTypeDoc, reactFullTypeDocSidebarGroup] =
+	createStarlightTypeDocPlugin();
+const [lyricStarlightTypeDoc, lyricTypeDocSidebarGroup] =
+	createStarlightTypeDocPlugin();
+
+// https://astro.build/config
+export default defineConfig({
+	base: "applemusic-like-lyrics",
+	integrations: [
+		starlight({
+			favicon: "favicon.ico",
+			title: "Apple Music-like Lyrics",
+			customCss: ["./src/styles/custom.css"],
+			locales: {
+				root: {
+					label: "简体中文",
+					lang: "zh-CN",
+				},
+				en: {
+					label: "English",
+					lang: "en",
+				},
+			},
+			social: {
+				github: "https://github.com/Steve-xmh/applemusic-like-lyrics",
+			},
+			plugins: [
+				coreStarlightTypeDoc({
+					entryPoints: ["../core/src/index.ts"],
+					output: "reference/core",
+					tsconfig: "../core/tsconfig.json",
+					sidebar: {
+						label: "core",
+						collapsed: true,
+					},
+					typeDoc: {
+						exclude: ["test.ts"],
+					},
+				}),
+				reactStarlightTypeDoc({
+					entryPoints: ["../react/src/index.ts"],
+					output: "reference/react",
+					tsconfig: "../react/tsconfig.json",
+					sidebar: {
+						label: "react",
+						collapsed: true,
+					},
+				}),
+				vueStarlightTypeDoc({
+					entryPoints: ["../vue/src/index.ts"],
+					output: "reference/vue",
+					tsconfig: "../vue/tsconfig.json",
+					sidebar: {
+						label: "vue",
+						collapsed: true,
+					},
+				}),
+				reactFullStarlightTypeDoc({
+					entryPoints: ["../react-full/src/index.ts"],
+					output: "reference/react-full",
+					tsconfig: "../react-full/tsconfig.json",
+					sidebar: {
+						label: "react-full",
+						collapsed: true,
+					},
+				}),
+				lyricStarlightTypeDoc({
+					entryPoints: ["../lyric/src/types.d.ts"],
+					output: "reference/lyric",
+					tsconfig: "../lyric/tsconfig.json",
+					sidebar: {
+						label: "lyric",
+						collapsed: true,
+					},
+				}),
+			],
+			sidebar: [
+				{
+					label: "核心组件",
+					items: [{ slug: "guides/core/introduction" }],
+				},
+				{
+					label: "React 绑定",
+					items: [
+						{ slug: "guides/react/introduction" },
+						{ slug: "guides/react/quick-start" },
+						{ slug: "guides/react/lyric-player" },
+						{ slug: "guides/react/bg-render" },
+					],
+				},
+				{
+					label: "AMLL TTML Tools",
+					items: [
+						{ slug: "guides/ttml-tools/introduction" },
+						{ slug: "guides/ttml-tools/tips" },
+					],
+				},
+				{
+					label: "接口参考",
+					items: [
+						coreTypeDocSidebarGroup,
+						reactTypeDocSidebarGroup,
+						vueTypeDocSidebarGroup,
+						reactFullTypeDocSidebarGroup,
+						lyricTypeDocSidebarGroup,
+					],
+				},
+			],
+		}),
+	],
+});

packages/docs/package.json

@@ -1,34 +1,22 @@
 {
   "name": "@applemusic-like-lyrics/docs",
-  "version": "0.1.0",
-  "private": true,
+  "type": "module",
+  "version": "0.0.1",
   "scripts": {
-    "dev": "next dev",
-    "build": "next build",
-    "start": "next start",
-    "lint": "next lint"
+    "dev": "astro dev",
+    "start": "astro dev",
+    "build": "astro build",
+    "preview": "astro preview",
+    "astro": "astro"
   },
   "dependencies": {
-    "@mdx-js/loader": "^3.1.0",
-    "@mdx-js/react": "^3.1.0",
-    "@next/mdx": "^15.0.3",
-    "@types/mdx": "^2.0.13",
-    "classnames": "^2.5.1",
-    "geist": "^1.3.1",
-    "highlight.js": "^11.10.0",
-    "next": "15.0.3",
-    "next-mdx-remote": "^5.0.0",
-    "react": "^18.3.1",
-    "react-dom": "^18.3.1",
-    "rehype-highlight": "^7.0.1",
-    "remark-frontmatter": "^5.0.0",
-    "remark-gfm": "4.0.0",
-    "remark-mdx-frontmatter": "^5.0.0"
+    "@astrojs/starlight": "^0.30.4",
+    "astro": "^5.0.2",
+    "sharp": "^0.32.5"
   },
   "devDependencies": {
-    "@types/node": "^22.9.0",
-    "@types/react": "^18.3.12",
-    "@types/react-dom": "^18.3.1",
-    "typescript": "^5.6.3"
+    "starlight-typedoc": "^0.18.0",
+    "typedoc": "^0.26.11",
+    "typedoc-plugin-markdown": "^4.2.10"
   }
-}
+}