🔧 fix(docs): unblock Next build by repairing MDX + OpenAPI references

t0ng7u · t0ng7u · commit de6e1e263556 · 2026-01-04T23:29:44.000+08:00
- Fix invalid MDX comment syntax in generated JA API doc (replace HTML comment with MDX-safe JSX comment)
- Repair broken `&lt;APIPage document={...}&gt;` JSON references in translated EN/JA docs to prevent prerender crashes
- Add missing `meta.json` files for EN/JA API roots to stabilize navigation/build
- Add a repeatable repair script: `scripts/repair-openapi-mdx.ts`

Build: `bun run build` now succeeds.
diff --git a/content/docs/en/api/ai-model/completions/createcompletion.mdx b/content/docs/en/api/ai-model/completions/createcompletion.mdx
@@ -14,4 +14,4 @@ _openapi:
 
 Create text completions based on a given prompt
 
-<APIPage document={"openapi/generated/ai-model/Completions/post-v1-completions-createcompletion-383826474.json"} operations={[{"path":"/v1/completions","method":"post"}]} />
+<APIPage document={"openapi/generated/ai-model/补全（Completions）/post-v1-completions-createcompletion-383826474.json"} operations={[{"path":"/v1/completions","method":"post"}]} />
diff --git a/content/docs/en/api/ai-model/images/qwen/createimage.mdx b/content/docs/en/api/ai-model/images/qwen/createimage.mdx
@@ -14,4 +14,4 @@ _openapi:
 
 Bailian qwen-image series image generation
 
-<APIPage document={"openapi/generated/ai-model/Images/Tongyi Qianwen OpenAI Format/post-v1-images-generations-createimage-383833512.json"} operations={[{"path":"/v1/images/generations","method":"post"}]} />
+<APIPage document={"openapi/generated/ai-model/图像（Images）/通义千问OpenAI格式/post-v1-images-generations-createimage-383833512.json"} operations={[{"path":"/v1/images/generations","method":"post"}]} />
diff --git a/content/docs/en/api/ai-model/meta.json b/content/docs/en/api/ai-model/meta.json
@@ -0,0 +1,3 @@
+{
+  "title": "AI Model API"
+}
diff --git a/content/docs/en/api/management/meta.json b/content/docs/en/api/management/meta.json
@@ -0,0 +1,3 @@
+{
+  "title": "Management API"
+}
diff --git a/content/docs/en/api/management/user-management/user-id-2fa-delete.mdx b/content/docs/en/api/management/user-management/user-id-2fa-delete.mdx
@@ -14,4 +14,4 @@ _openapi:
 
 👨‍💼 Admin Permissions Required (Admin)
 
-<APIPage document={"openapi/generated/management/User Management/delete-api-user-id-2fa-delete-api-user-id-2fa-384083868.json"} operations={[{"path":"/api/user/{id}/2fa","method":"delete"}]} />
+<APIPage document={"openapi/generated/management/用户管理/delete-api-user-id-2fa-delete-api-user-id-2fa-384083868.json"} operations={[{"path":"/api/user/{id}/2fa","method":"delete"}]} />
diff --git a/content/docs/en/api/meta.json b/content/docs/en/api/meta.json
@@ -0,0 +1,3 @@
+{
+  "title": "API"
+}
diff --git a/content/docs/en/guide/wiki/changelog.mdx b/content/docs/en/guide/wiki/changelog.mdx
@@ -4,7 +4,7 @@ title: Changelog
 
 import { Callout } from 'fumadocs-ui/components/callout';
 
-<Callout type="warn" title="Version Log Information · Data updated at 2026-1-3 13:19:22">
+<Callout type="warn" title="Version Log Information · Data updated at 2026-1-4 23:18:11">
 To view all historical versions, please visit the [GitHub Releases page](https://github.com/QuantumNous/new-api/releases). This page automatically fetches the latest update information from that page.
 </Callout>
 
diff --git a/content/docs/en/guide/wiki/special-thanks.mdx b/content/docs/en/guide/wiki/special-thanks.mdx
@@ -10,7 +10,7 @@ The development of New API would not be possible without the support and contrib
 
 Below is a list of all developers who have contributed to the project. We thank them for their hard work and creativity!
 
-<Callout title="Contributor Information · Data updated at 2026-1-3 13:19:22 (UTC+8)">
+<Callout title="Contributor Information · Data updated at 2026-1-4 23:18:11 (UTC+8)">
 The following contributor data is automatically retrieved from the [GitHub Contributors page](https://github.com/QuantumNous/new-api/graphs/contributors) for the top 50 contributors. The top three contributors are marked with gold, silver, and bronze borders respectively. If you would also like to contribute to the project, you are welcome to submit a Pull Request.
 </Callout>
 
@@ -22,7 +22,7 @@ The following contributor data is automatically retrieved from the [GitHub Contr
   </div>
   <div className="flex flex-col">
     <a href="https://github.com/Calcium-Ion" target="_blank" rel="noopener noreferrer" className="font-medium no-underline mb-1">Calcium-Ion</a>
-    <span className="text-sm text-muted-foreground">Contributions: 2306</span>
+    <span className="text-sm text-muted-foreground">Contributions: 2308</span>
   </div>
 </div>
 
@@ -64,7 +64,7 @@ The following contributor data is automatically retrieved from the [GitHub Contr
   </div>
   <div className="flex flex-col">
     <a href="https://github.com/seefs001" target="_blank" rel="noopener noreferrer" className="font-medium no-underline mb-1">seefs001</a>
-    <span className="text-sm text-muted-foreground">Contributions: 283</span>
+    <span className="text-sm text-muted-foreground">Contributions: 284</span>
   </div>
 </div>
 
@@ -120,7 +120,7 @@ The following contributor data is automatically retrieved from the [GitHub Contr
   </div>
   <div className="flex flex-col">
     <a href="https://github.com/xyfacai" target="_blank" rel="noopener noreferrer" className="font-medium no-underline mb-1">xyfacai</a>
-    <span className="text-sm text-muted-foreground">Contributions: 49</span>
+    <span className="text-sm text-muted-foreground">Contributions: 50</span>
   </div>
 </div>
 
diff --git a/content/docs/ja/api/ai-model/meta.json b/content/docs/ja/api/ai-model/meta.json
@@ -0,0 +1,3 @@
+{
+  "title": "AIモデルAPI"
+}
diff --git a/content/docs/ja/api/management/meta.json b/content/docs/ja/api/management/meta.json
@@ -0,0 +1,3 @@
+{
+  "title": "管理API"
+}
diff --git a/content/docs/ja/api/management/two-factor-auth/user-2fa-stats-get.mdx b/content/docs/ja/api/management/two-factor-auth/user-2fa-stats-get.mdx
@@ -10,7 +10,7 @@ _openapi:
       - content: 👨‍💼 管理者権限（Admin）が必要です
 ---
 
-<!-- このファイルはFumadocsによって生成されました。このファイルを直接編集しないでください。変更を加える場合は、再度生成コマンドを実行してください。 -->
+{/* このファイルはFumadocsによって生成されました。このファイルを直接編集しないでください。変更を加える場合は、再度生成コマンドを実行してください。 */}
 
 👨‍💼 管理者権限（Admin）が必要です
 
diff --git a/content/docs/ja/api/meta.json b/content/docs/ja/api/meta.json
@@ -0,0 +1,3 @@
+{
+  "title": "API"
+}
diff --git a/content/docs/ja/guide/wiki/changelog.mdx b/content/docs/ja/guide/wiki/changelog.mdx
@@ -4,7 +4,7 @@ title: 変更履歴
 
 import { Callout } from 'fumadocs-ui/components/callout';
 
-<Callout type="warn" title="バージョンログ情報 · データ更新日時 2026-1-3 13:19:22">
+<Callout type="warn" title="バージョンログ情報 · データ更新日時 2026-1-4 23:18:11">
 すべての履歴バージョンを表示するには、[GitHub Releases ページ](https://github.com/QuantumNous/new-api/releases)をご覧ください。このページは定期的に最新の更新情報を取得します。
 </Callout>
 
diff --git a/content/docs/ja/guide/wiki/special-thanks.mdx b/content/docs/ja/guide/wiki/special-thanks.mdx
@@ -10,7 +10,7 @@ New API の開発は、コミュニティのサポートと貢献なしには実
 
 以下は、プロジェクトに貢献してくださったすべての開発者のリストです。彼らの勤勉な作業と創造性に感謝します！
 
-<Callout title="貢献者情報 · データ更新日時 2026-1-3 13:19:22 (UTC+8)">
+<Callout title="貢献者情報 · データ更新日時 2026-1-4 23:18:11 (UTC+8)">
 以下の貢献者データは、[GitHub Contributors ページ](https://github.com/QuantumNous/new-api/graphs/contributors)から上位50名を自動的に取得します。貢献度上位3名は、それぞれゴールド、シルバー、ブロンズの枠で識別されます。プロジェクトに貢献したい場合は、プルリクエストを送信してください。
 </Callout>
 
@@ -22,7 +22,7 @@ New API の開発は、コミュニティのサポートと貢献なしには実
   </div>
   <div className="flex flex-col">
     <a href="https://github.com/Calcium-Ion" target="_blank" rel="noopener noreferrer" className="font-medium no-underline mb-1">Calcium-Ion</a>
-    <span className="text-sm text-muted-foreground">貢献回数: 2306</span>
+    <span className="text-sm text-muted-foreground">貢献回数: 2308</span>
   </div>
 </div>
 
@@ -64,7 +64,7 @@ New API の開発は、コミュニティのサポートと貢献なしには実
   </div>
   <div className="flex flex-col">
     <a href="https://github.com/seefs001" target="_blank" rel="noopener noreferrer" className="font-medium no-underline mb-1">seefs001</a>
-    <span className="text-sm text-muted-foreground">貢献回数: 283</span>
+    <span className="text-sm text-muted-foreground">貢献回数: 284</span>
   </div>
 </div>
 
@@ -120,7 +120,7 @@ New API の開発は、コミュニティのサポートと貢献なしには実
   </div>
   <div className="flex flex-col">
     <a href="https://github.com/xyfacai" target="_blank" rel="noopener noreferrer" className="font-medium no-underline mb-1">xyfacai</a>
-    <span className="text-sm text-muted-foreground">貢献回数: 49</span>
+    <span className="text-sm text-muted-foreground">貢献回数: 50</span>
   </div>
 </div>
 
diff --git a/content/docs/zh/guide/wiki/changelog.mdx b/content/docs/zh/guide/wiki/changelog.mdx
@@ -4,7 +4,7 @@ title: 更新日志
 
 import { Callout } from 'fumadocs-ui/components/callout';
 
-<Callout type="warn" title="版本日志信息 · 数据更新于 2026-1-3 13:19:22">
+<Callout type="warn" title="版本日志信息 · 数据更新于 2026-1-4 23:18:11">
 如需查看全部历史版本，请访问 [GitHub Releases 页面](https://github.com/QuantumNous/new-api/releases)，本页面从该页面定时获取最新更新信息。
 </Callout>
 
diff --git a/content/docs/zh/guide/wiki/special-thanks.mdx b/content/docs/zh/guide/wiki/special-thanks.mdx
@@ -10,7 +10,7 @@ New API 的开发离不开社区的支持和贡献。在此特别感谢所有为
 
 以下是所有为项目做出贡献的开发者列表。在此感谢他们的辛勤工作和创意！
 
-<Callout title="贡献者信息 · 数据更新于 2026-1-3 13:19:21 (UTC+8)">
+<Callout title="贡献者信息 · 数据更新于 2026-1-4 23:18:11 (UTC+8)">
 以下贡献者数据从 [GitHub Contributors 页面](https://github.com/QuantumNous/new-api/graphs/contributors) 自动获取前50名。贡献度前三名分别以金、银、铜牌边框标识。如果您也想为项目做出贡献，欢迎提交 Pull Request。
 </Callout>
 
@@ -22,7 +22,7 @@ New API 的开发离不开社区的支持和贡献。在此特别感谢所有为
   </div>
   <div className="flex flex-col">
     <a href="https://github.com/Calcium-Ion" target="_blank" rel="noopener noreferrer" className="font-medium no-underline mb-1">Calcium-Ion</a>
-    <span className="text-sm text-muted-foreground">贡献次数: 2306</span>
+    <span className="text-sm text-muted-foreground">贡献次数: 2308</span>
   </div>
 </div>
 
@@ -64,7 +64,7 @@ New API 的开发离不开社区的支持和贡献。在此特别感谢所有为
   </div>
   <div className="flex flex-col">
     <a href="https://github.com/seefs001" target="_blank" rel="noopener noreferrer" className="font-medium no-underline mb-1">seefs001</a>
-    <span className="text-sm text-muted-foreground">贡献次数: 283</span>
+    <span className="text-sm text-muted-foreground">贡献次数: 284</span>
   </div>
 </div>
 
@@ -120,7 +120,7 @@ New API 的开发离不开社区的支持和贡献。在此特别感谢所有为
   </div>
   <div className="flex flex-col">
     <a href="https://github.com/xyfacai" target="_blank" rel="noopener noreferrer" className="font-medium no-underline mb-1">xyfacai</a>
-    <span className="text-sm text-muted-foreground">贡献次数: 49</span>
+    <span className="text-sm text-muted-foreground">贡献次数: 50</span>
   </div>
 </div>
 
diff --git a/scripts/repair-openapi-mdx.ts b/scripts/repair-openapi-mdx.ts
@@ -0,0 +1,153 @@
+/**
+ * Repair translated OpenAPI MDX files.
+ *
+ * Problem:
+ * - Some translated MDX files (en/ja) have `<APIPage document={"openapi/generated/..."} />`
+ *   paths that no longer match the actual JSON file location under `openapi/generated/**`.
+ * - This causes prerender failures like: "Cannot destructure property 'dereferenced' ... undefined".
+ *
+ * This script:
+ * - Builds an index of all JSON files under `openapi/generated/` (recursive) by basename.
+ * - Scans `content/docs/{en,ja}/api/` (recursive) MDX files for `document={"...json"}` paths.
+ * - If a referenced JSON doesn't exist, it rewrites it to the unique matching JSON path by basename.
+ */
+
+import { readdir, readFile, stat, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+
+type Locale = 'en' | 'ja';
+
+function toPosix(p: string): string {
+  return p.split(path.sep).join('/');
+}
+
+async function walkFiles(
+  root: string,
+  predicate: (filePath: string) => boolean
+): Promise<string[]> {
+  const out: string[] = [];
+  async function walk(dir: string) {
+    let entries: Array<{ name: string; isDirectory: boolean; isFile: boolean }>;
+    try {
+      entries = (await readdir(dir, { withFileTypes: true })) as any;
+    } catch {
+      return;
+    }
+    for (const e of entries as any) {
+      const full = path.join(dir, e.name);
+      if (e.isDirectory()) await walk(full);
+      else if (e.isFile() && predicate(full)) out.push(full);
+    }
+  }
+  await walk(root);
+  return out;
+}
+
+async function buildOpenApiIndex(): Promise<Map<string, string[]>> {
+  const root = path.join(process.cwd(), 'openapi', 'generated');
+  const files = await walkFiles(root, (p) => p.toLowerCase().endsWith('.json'));
+  const index = new Map<string, string[]>();
+  for (const abs of files) {
+    const base = path.basename(abs);
+    const rel = toPosix(path.relative(process.cwd(), abs));
+    const arr = index.get(base) ?? [];
+    arr.push(rel);
+    index.set(base, arr);
+  }
+  return index;
+}
+
+function extractDocumentPaths(mdx: string): string[] {
+  const re = /document=\{"(openapi\/generated\/[^"]+?\.json)"\}/g;
+  const out: string[] = [];
+  for (let m; (m = re.exec(mdx)); ) {
+    out.push(m[1]);
+  }
+  return out;
+}
+
+async function pathExists(relPosix: string): Promise<boolean> {
+  const abs = path.join(process.cwd(), ...relPosix.split('/'));
+  try {
+    const s = await stat(abs);
+    return s.isFile();
+  } catch {
+    return false;
+  }
+}
+
+async function repairLocale(locale: Locale, index: Map<string, string[]>) {
+  const root = path.join(process.cwd(), 'content', 'docs', locale, 'api');
+  const mdxFiles = await walkFiles(root, (p) =>
+    p.toLowerCase().endsWith('.mdx')
+  );
+
+  let changedFiles = 0;
+  let fixedRefs = 0;
+  let unresolvedRefs = 0;
+
+  for (const absMdx of mdxFiles) {
+    const original = await readFile(absMdx, 'utf8');
+    const docPaths = extractDocumentPaths(original);
+    if (docPaths.length === 0) continue;
+
+    let next = original;
+    let touched = false;
+
+    for (const docPath of docPaths) {
+      // If it already exists, nothing to do.
+      // (Paths are stored as POSIX in MDX)
+      // eslint-disable-next-line no-await-in-loop
+      if (await pathExists(docPath)) continue;
+
+      const base = path.basename(docPath);
+      const candidates = index.get(base) ?? [];
+
+      if (candidates.length === 1) {
+        const replacement = candidates[0];
+        next = next
+          .split(`document={"${docPath}"}`)
+          .join(`document={"${replacement}"}`);
+        touched = true;
+        fixedRefs++;
+      } else {
+        unresolvedRefs++;
+      }
+    }
+
+    if (touched && next !== original) {
+      await writeFile(absMdx, next, 'utf8');
+      changedFiles++;
+    }
+  }
+
+  return {
+    locale,
+    changedFiles,
+    fixedRefs,
+    unresolvedRefs,
+    totalFiles: mdxFiles.length,
+  };
+}
+
+async function main() {
+  const index = await buildOpenApiIndex();
+  const locales: Locale[] = ['en', 'ja'];
+  const results = [];
+  for (const locale of locales) {
+    // eslint-disable-next-line no-await-in-loop
+    results.push(await repairLocale(locale, index));
+  }
+
+  // Keep output compact but informative for CI/build logs.
+  for (const r of results) {
+    console.log(
+      `[repair-openapi-mdx] ${r.locale}: scanned=${r.totalFiles}, changed=${r.changedFiles}, fixedRefs=${r.fixedRefs}, unresolvedRefs=${r.unresolvedRefs}`
+    );
+  }
+}
+
+main().catch((err) => {
+  console.error('[repair-openapi-mdx] failed:', err);
+  process.exit(1);
+});

Original file line number	Diff line number	Diff line change
`@@ -14,4 +14,4 @@ _openapi:`
`14`	`14`
`15`	`15`	`Create text completions based on a given prompt`
`16`	`16`
`17`		`-<APIPage document={"openapi/generated/ai-model/Completions/post-v1-completions-createcompletion-383826474.json"} operations={[{"path":"/v1/completions","method":"post"}]} />`
	`17`	`+<APIPage document={"openapi/generated/ai-model/补全（Completions）/post-v1-completions-createcompletion-383826474.json"} operations={[{"path":"/v1/completions","method":"post"}]} />`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "title": "AI Model API"`
	`3`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "title": "Management API"`
	`3`	`+}`
Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+{`
	`2`	`+ "title": "AIモデルAPI"`
	`3`	`+}`