openmanual 0.13.0 → 0.14.1

package/dist/bin.js

@@ -7,6 +7,8 @@ import { Command } from "commander";
 import { spawn } from "node:child_process";
 import { access, cp, lstat, mkdir, readFile, readdir, rm, symlink, writeFile } from "node:fs/promises";
 import { z } from "zod";
+import fg from "fast-glob";
+import matter from "gray-matter";
 
 //#region src/core/config/schema.ts
 const LogoSchema = z.union([z.string(), z.object({
@@ -38,7 +40,7 @@ const ThemeSchema = z.object({
 	primaryHue: z.number().min(0).max(360).optional(),
 	darkMode: z.boolean().optional()
 });
-const SearchSchema = z.object({ enabled: z.boolean().optional() });
+const SearchSchema = z.object({ position: z.enum(["sidebar", "header"]).optional() });
 const MdxSchema = z.object({ latex: z.boolean().optional() });
 const PageActionsSchema = z.object({ enabled: z.boolean().optional() });
 const I18nLocaleSchema = z.object({
@@ -51,6 +53,40 @@ const I18nConfigSchema = z.object({
 	languages: z.array(I18nLocaleSchema).optional(),
 	parser: z.enum(["dot", "dir"]).optional()
 });
+const OpenApiSpecSchema = z.object({
+	path: z.string(),
+	group: z.string().optional()
+});
+const OpenApiSchema = z.object({
+	specPath: z.string().optional(),
+	specs: z.union([z.string(), z.array(OpenApiSpecSchema)]).optional(),
+	label: z.string().optional(),
+	groupBy: z.enum([
+		"tag",
+		"route",
+		"none"
+	]).optional().default("tag"),
+	separateTab: z.boolean().optional().default(false)
+});
+/** 顶部横条链接项 */
+const TopBarLinkSchema = z.object({
+	label: z.string().optional(),
+	icon: z.string().optional(),
+	href: z.string(),
+	external: z.boolean().optional().default(true)
+}).refine((data) => data.label || data.icon, {
+	message: "至少需要提供 label 或 icon 中的一个",
+	path: ["label"]
+});
+/** 顶部横条配置 */
+const TopBarSchema = z.object({
+	height: z.string().optional(),
+	logo: LogoSchema.optional(),
+	links: z.array(TopBarLinkSchema).optional(),
+	sticky: z.boolean().optional().default(true),
+	background: z.string().optional(),
+	bordered: z.boolean().optional().default(true)
+});
 const OpenManualConfigSchema = z.object({
 	name: z.string().min(1),
 	description: z.string().optional(),
@@ -61,25 +97,54 @@ const OpenManualConfigSchema = z.object({
 	contentPolicy: z.enum(["strict", "all"]).optional(),
 	favicon: FaviconSchema.optional(),
 	navbar: NavbarSchema.optional(),
+	header: TopBarSchema.optional(),
 	footer: FooterSchema.optional(),
 	sidebar: z.array(SidebarGroupSchema).optional(),
 	theme: ThemeSchema.optional(),
 	search: SearchSchema.optional(),
 	mdx: MdxSchema.optional(),
 	pageActions: PageActionsSchema.optional(),
-	i18n: I18nConfigSchema.optional()
+	i18n: I18nConfigSchema.optional(),
+	openapi: OpenApiSchema.optional()
 });
-function collectConfiguredSlugs(config) {
-	const slugs = /* @__PURE__ */ new Set();
-	if (config.sidebar) for (const group of config.sidebar) for (const page of group.pages) slugs.add(page.slug);
-	return slugs;
-}
 function isI18nEnabled(config) {
 	return config.i18n?.enabled === true && (config.i18n.languages?.length ?? 0) > 1;
 }
 function isDirParser(config) {
 	return config.i18n?.parser === "dir";
 }
+function isOpenApiEnabled(config) {
+	if (config.openapi === void 0) return false;
+	const hasSpecs = config.openapi.specs !== void 0;
+	const hasSpecPath = typeof config.openapi?.specPath === "string";
+	return hasSpecs || hasSpecPath;
+}
+/**
+* 从 OpenAPI 配置中解析出所有 spec 文件路径
+* 兼容 specs（新）和 specPath（旧）两种格式
+*/
+function resolveOpenApiSpecPaths(config) {
+	const openApiCfg = config.openapi;
+	if (!openApiCfg) return [];
+	if (openApiCfg.specs !== void 0) {
+		if (typeof openApiCfg.specs === "string") return [openApiCfg.specs];
+		return openApiCfg.specs.map((s) => s.path);
+	}
+	if (typeof openApiCfg.specPath === "string") return [openApiCfg.specPath];
+	return [];
+}
+/**
+* 判断是否使用独立 Tab 模式（旧行为）
+*/
+function isSeparateTabMode(config) {
+	return config.openapi?.separateTab === true;
+}
+/**
+* 判断是否启用了顶部横条（配置了 header 即启用）
+*/
+function isHeaderEnabled(config) {
+	return config.header !== void 0;
+}
 
 //#endregion
 //#region src/core/config/loader.ts
@@ -93,7 +158,6 @@ const DEFAULT_CONFIG = {
 		primaryHue: 213,
 		darkMode: true
 	},
-	search: { enabled: true },
 	mdx: {},
 	pageActions: { enabled: true }
 };
@@ -139,10 +203,7 @@ function mergeDefaults(config) {
 			...DEFAULT_CONFIG.theme,
 			...config.theme
 		},
-		search: {
-			...DEFAULT_CONFIG.search,
-			...config.search
-		},
+		search: config.search ? { position: config.search.position ?? "sidebar" } : void 0,
 		mdx: {
 			...DEFAULT_CONFIG.mdx,
 			...config.mdx
@@ -156,10 +217,125 @@ function mergeDefaults(config) {
 			defaultLanguage: config.i18n.defaultLanguage ?? config.locale ?? "zh",
 			languages: config.i18n.languages ?? [],
 			parser: config.i18n.parser ?? "dot"
+		} : void 0,
+		openapi: config.openapi ? {
+			specPath: config.openapi.specPath,
+			specs: config.openapi.specs,
+			label: config.openapi.label ?? "接口文档",
+			groupBy: config.openapi.groupBy ?? "tag",
+			separateTab: config.openapi.separateTab ?? false
 		} : void 0
 	};
 }
 
+//#endregion
+//#region src/core/content/meta-scanner.ts
+async function scanMetaFiles(contentAbsDir, languages, useDirParser) {
+	let patterns;
+	if (useDirParser) patterns = languages.map((lang) => `${lang}/**/meta.json`);
+	else {
+		patterns = ["**/meta.json"];
+		if (languages.length > 1) for (const lang of languages) patterns.push(`**/meta.${lang}.json`);
+	}
+	const entries = await fg(patterns, {
+		cwd: contentAbsDir,
+		absolute: true,
+		ignore: ["node_modules"]
+	});
+	const groups = [];
+	for (const filePath of entries) {
+		const group = await parseMetaFile(filePath, contentAbsDir, languages, useDirParser);
+		if (group) groups.push(group);
+	}
+	return groups;
+}
+async function parseMetaFile(filePath, contentAbsDir, languages, useDirParser) {
+	try {
+		const raw = await readFile(filePath, "utf-8");
+		const data = JSON.parse(raw);
+		if (typeof data.title !== "string" || data.title.length === 0) return null;
+		const relPath = filePath.replace(contentAbsDir, "").replace(/^\/+/, "");
+		const dirPath = relPath.replace(/\/?meta(\.[^/]+)?\.json$/, "");
+		let isRoot = false;
+		if (useDirParser) isRoot = languages.includes(dirPath);
+		else {
+			if (/meta\.\w{2}(-\w{2})?\.json$/.test(relPath) && languages.length > 1) return null;
+			isRoot = dirPath === "";
+		}
+		const group = {
+			filePath,
+			dirPath,
+			isRoot,
+			title: data.title
+		};
+		if (typeof data.icon === "string") group.icon = data.icon;
+		if (typeof data.root === "boolean") group.root = data.root;
+		if (typeof data.defaultOpen === "boolean") group.defaultOpen = data.defaultOpen;
+		if (Array.isArray(data.pages)) group.pages = data.pages.filter((p) => typeof p === "string");
+		return group;
+	} catch {
+		return null;
+	}
+}
+/**
+* Collect all slugs from meta group infos.
+*
+* For root-level groups, page filenames are used directly as slugs.
+* For directory-level groups, page filenames are prefixed with the directory path.
+*/
+function collectSlugsFromMeta(groups) {
+	const slugs = /* @__PURE__ */ new Set();
+	for (const group of groups) {
+		if (!group.pages) continue;
+		for (const page of group.pages) if (group.isRoot) slugs.add(page);
+		else {
+			const slug = `${group.dirPath}/${page}`;
+			slugs.add(slug);
+		}
+	}
+	return slugs;
+}
+
+//#endregion
+//#region src/core/content/scanner.ts
+async function scanContentDir(contentDir) {
+	const entries = await fg("**/*.{md,mdx}", {
+		cwd: contentDir,
+		absolute: true,
+		ignore: ["node_modules"]
+	});
+	const files = [];
+	for (const filePath of entries) {
+		const file = await parseContentFile(filePath, contentDir);
+		if (file) files.push(file);
+	}
+	return files.sort((a, b) => a.slug.localeCompare(b.slug));
+}
+async function parseContentFile(filePath, contentDir) {
+	try {
+		const { data: frontmatter, content } = matter(await readFile(filePath, "utf-8"));
+		const segments = relative(contentDir, filePath).replace(/\.(md|mdx)$/, "").split(sep);
+		const name = segments.at(-1) ?? "";
+		return {
+			filePath,
+			slug: segments.join("/"),
+			name,
+			frontmatter,
+			content,
+			segments
+		};
+	} catch {
+		return null;
+	}
+}
+
+//#endregion
+//#region src/core/content/tree.ts
+/** Format a directory name into a display title (e.g. "my-page" → "My Page") */
+function formatTitle(name) {
+	return name.replace(/[-_]/g, " ").replace(/\b\w/g, (c) => c.toUpperCase());
+}
+
 //#endregion
 //#region src/core/generator/callout-component.ts
 function generateCalloutComponent() {
@@ -173,45 +349,9 @@ export { Callout, CalloutTitle, CalloutDescription } from 'openmanual/components
 function generateGlobalCss(ctx) {
 	const { config } = ctx;
 	const primaryHue = config.theme?.primaryHue ?? 213;
-	return `@import 'tailwindcss';
-@source './node_modules/openmanual/dist/components/**/*.js';
-@import 'fumadocs-ui/style.css';
-@custom-variant dark (&:is(.dark, .dark *));
-
-:root {
-  --primary-hue: ${primaryHue};
-
-  /* 护眼暖色阅读背景 */
-  --color-fd-background: hsl(40, 22%, 96.5%);     /* #faf9f6 纸张白 */
-  --color-fd-foreground: hsl(0, 0%, 17.3%);        /* #2c2c2c 柔黑 */
-  --color-fd-muted: hsl(40, 15%, 95%);             /* 柔和的暖灰背景 */
-  --color-fd-card: hsl(40, 18%, 94%);              /* 卡片背景 */
-  --color-fd-popover: hsl(40, 20%, 97.5%);         /* 弹窗背景 */
-
-  /* Callout 类型色 */
-  --callout-info-bg: hsl(210, 35%, 94%);
-  --callout-info-border: hsl(212, 40%, 80%);
-  --callout-info-text: hsl(213, 45%, 35%);
-  --callout-warning-bg: hsl(38, 60%, 93%);
-  --callout-warning-border: hsl(36, 55%, 78%);
-  --callout-warning-text: hsl(28, 55%, 35%);
-  --callout-danger-bg: hsl(0, 50%, 94%);
-  --callout-danger-border: hsl(0, 45%, 82%);
-  --callout-danger-text: hsl(0, 50%, 38%);
-  --callout-check-bg: hsl(150, 35%, 93%);
-  --callout-check-border: hsl(152, 35%, 78%);
-  --callout-check-text: hsl(155, 40%, 32%);
-  --callout-tip-bg: hsl(150, 35%, 93%);
-  --callout-tip-border: hsl(152, 35%, 78%);
-  --callout-tip-text: hsl(155, 40%, 32%);
-  --callout-note-bg: hsl(215, 20%, 94%);
-  --callout-note-border: hsl(215, 22%, 82%);
-  --callout-note-text: hsl(215, 25%, 40%);
-  --callout-key-bg: hsl(30, 55%, 93%);
-  --callout-key-border: hsl(28, 50%, 78%);
-  --callout-key-text: hsl(25, 50%, 35%);
-}
-${config.theme?.darkMode ?? true ? `
+	const darkMode = config.theme?.darkMode ?? true;
+	const isOApi = isOpenApiEnabled(config);
+	const darkBlock = darkMode ? `
 .dark {
   --primary-hue: ${primaryHue};
 
@@ -233,6 +373,7 @@ ${config.theme?.darkMode ?? true ? `
   --color-fd-accent-foreground: hsl(35, 12%, 88%);
   --color-fd-ring: hsl(30, 30%, 50%);
   --color-fd-overlay: hsla(25, 20%, 5%, 0.5);
+  --color-fd-inputborder: hsla(30, 20%, 50%, 40%);   /* 输入框边框色（hover 用）*/
 
   /* Callout 类型色 */
   --callout-info-bg: hsl(213, 25%, 16%);
@@ -261,7 +402,59 @@ ${config.theme?.darkMode ?? true ? `
 .dark body {
   background: linear-gradient(hsla(30, 30%, 15%, 0.4), transparent 20rem, transparent);
 }
-` : ""}
+` : "";
+	return `@import 'tailwindcss';
+@source './node_modules/openmanual/dist/components/**/*.js';
+@import 'fumadocs-ui/css/neutral.css';
+@import 'fumadocs-ui/css/preset.css';${isOApi ? "\n@import 'fumadocs-openapi/css/preset.css';" : ""}
+
+@layer base {
+  body {
+    @apply flex flex-col min-h-screen;
+  }
+}
+
+/* 注册自定义颜色到 Tailwind v4 @theme，确保所有变体（hover/dark 等）可正确生成 */
+@theme {
+  --color-fd-inputborder: hsla(30, 12%, 80%, 50%);
+}
+
+:root {
+  --primary-hue: ${primaryHue};
+
+  /* 护眼暖色阅读背景 */
+  --color-fd-background: hsl(40, 22%, 96.5%);     /* #faf9f6 纸张白 */
+  --color-fd-foreground: hsl(0, 0%, 17.3%);        /* #2c2c2c 柔黑 */
+  --color-fd-muted: hsl(40, 15%, 95%);             /* 柔和的暖灰背景 */
+  --color-fd-card: hsl(40, 18%, 94%);              /* 卡片背景 */
+  --color-fd-popover: hsl(40, 20%, 97.5%);         /* 弹窗背景 */
+  --color-fd-muted-foreground: hsl(30, 10%, 55%);   /* 次要文字色 */
+  --color-fd-inputborder: hsla(30, 12%, 80%, 50%);  /* 输入框边框色（hover 用）*/
+
+  /* Callout 类型色 */
+  --callout-info-bg: hsl(210, 35%, 94%);
+  --callout-info-border: hsl(212, 40%, 80%);
+  --callout-info-text: hsl(213, 45%, 35%);
+  --callout-warning-bg: hsl(38, 60%, 93%);
+  --callout-warning-border: hsl(36, 55%, 78%);
+  --callout-warning-text: hsl(28, 55%, 35%);
+  --callout-danger-bg: hsl(0, 50%, 94%);
+  --callout-danger-border: hsl(0, 45%, 82%);
+  --callout-danger-text: hsl(0, 50%, 38%);
+  --callout-check-bg: hsl(150, 35%, 93%);
+  --callout-check-border: hsl(152, 35%, 78%);
+  --callout-check-text: hsl(155, 40%, 32%);
+  --callout-tip-bg: hsl(150, 35%, 93%);
+  --callout-tip-border: hsl(152, 35%, 78%);
+  --callout-tip-text: hsl(155, 40%, 32%);
+  --callout-note-bg: hsl(215, 20%, 94%);
+  --callout-note-border: hsl(215, 22%, 82%);
+  --callout-note-text: hsl(215, 25%, 40%);
+  --callout-key-bg: hsl(30, 55%, 93%);
+  --callout-key-border: hsl(28, 50%, 78%);
+  --callout-key-text: hsl(25, 50%, 35%);
+}
+${darkBlock}
 
 /* 代码块：去除 shadow，使用朴素边框；去除 max-height 限制 */
 figure.shiki {
@@ -286,6 +479,13 @@ figure.shiki > div {
 [style*="--callout-color"] {
   box-shadow: none;
 }
+${config.search?.position === "header" ? `
+
+/* header 搜索模式：隐藏侧边栏折叠面板中的搜索图标 */
+[data-sidebar-panel] [data-search] {
+  display: none;
+}
+` : ""}
 `;
 }
 
@@ -354,17 +554,25 @@ function resolveLogoPaths(logo) {
 		dark: logo.dark
 	};
 }
+/**
+* 将 LogoConfig 解析为 NavLogo 组件的 props 字符串
+*
+* 消除 top-bar.ts 和 layout.ts 中重复的三分支判断。
+*/
+function resolveNavLogoProps(logo, alt) {
+	if (typeof logo === "string" && isImagePath(logo)) return `type="image" src="${logo}" alt="${alt}"`;
+	if (typeof logo === "object") {
+		const { light, dark } = resolveLogoPaths(logo);
+		if (light === dark) return `type="image" src="${light}" alt="${alt}"`;
+		return `type="image" srcLight="${light}" srcDark="${dark}" alt="${alt}"`;
+	}
+	return `type="text" text="${logo}"`;
+}
 function generateLayout(ctx) {
 	const { config } = ctx;
 	const logo = config.navbar?.logo ?? config.name;
 	const isI18n = config.i18n?.enabled === true;
-	let logoProps;
-	if (typeof logo === "string" && isImagePath(logo)) logoProps = `type="image" src="${logo}" alt="${config.name}"`;
-	else if (typeof logo === "object") {
-		const { light, dark } = logo;
-		if (light === dark) logoProps = `type="image" src="${light}" alt="${config.name}"`;
-		else logoProps = `type="image" srcLight="${light}" srcDark="${dark}" alt="${config.name}"`;
-	} else logoProps = `type="text" text="${logo}"`;
+	const logoProps = resolveNavLogoProps(logo, config.name);
 	if (isI18n) return `import type { BaseLayoutProps } from 'fumadocs-ui/layouts/shared';
 import type { ReactNode } from 'react';
 import { NavLogo } from 'openmanual/components/nav-layout';
@@ -394,7 +602,58 @@ export function baseOptions(): BaseLayoutProps {
 //#endregion
 //#region src/core/generator/lib-source.ts
 function generateLibSource(ctx) {
-	if (ctx.config.i18n?.enabled === true) return `import { docs } from '@/.source/server';
+	const isI18n = isI18nEnabled(ctx.config);
+	if (isOpenApiEnabled(ctx.config)) {
+		const separateTab = isSeparateTabMode(ctx.config);
+		const groupBy = ctx.config.openapi?.groupBy ?? "tag";
+		if (isI18n) return `import { docs } from '@/.source/server';
+import { loader, multiple } from 'fumadocs-core/source';
+import { openapiPlugin, openapiSource } from 'fumadocs-openapi/server';
+import { openapi } from '@/lib/openapi';
+import { i18n } from '@/lib/i18n';
+
+const _omOpenApiFiles = [];
+for (const lang of i18n.languages) {
+  const result = await openapiSource(openapi, {
+    baseDir: \`\${lang}/${separateTab ? "openapi" : "api"}\`,
+${!separateTab ? `    meta: true,\n    groupBy: '${groupBy}',` : ""}
+  });
+  _omOpenApiFiles.push(...result.files);
+}
+
+export const source = loader(
+  multiple({
+    docs: docs.toFumadocsSource(),
+    openapi: { files: _omOpenApiFiles },
+  }),
+  {
+    baseUrl: '/',
+    i18n,
+    plugins: [openapiPlugin()],
+  },
+);
+`;
+		return `import { docs } from '@/.source/server';
+import { loader, multiple } from 'fumadocs-core/source';
+import { openapiPlugin, openapiSource } from 'fumadocs-openapi/server';
+import { openapi } from '@/lib/openapi';
+
+export const source = loader(
+  multiple({
+    docs: docs.toFumadocsSource(),
+    openapi: await openapiSource(openapi, {
+      baseDir: '${separateTab ? "openapi" : "api"}',
+${!separateTab ? `      meta: true,\n      groupBy: '${groupBy}',` : ""}
+    }),
+  }),
+  {
+    baseUrl: '/',
+    plugins: [openapiPlugin()],
+  },
+);
+`;
+	}
+	if (isI18n) return `import { docs } from '@/.source/server';
 import { loader } from 'fumadocs-core/source';
 import { i18n } from '@/lib/i18n';
 
@@ -462,34 +721,84 @@ export const config = {
 function generateNextConfig(ctx) {
 	const { config } = ctx;
 	const siteUrl = config.siteUrl ?? "";
+	const isOApi = isOpenApiEnabled(config);
+	const outputLine = !ctx.dev && siteUrl ? `\n  output: 'export',` : "";
+	const rewritesBlock = ctx.dev ? `\n  async rewrites() {\n    return [{ source: '/:path(.+)\\\\.md', destination: '/api/raw/:path' }];\n  },` : "";
 	return `import { createMDX } from 'fumadocs-mdx/next';
 
 const withMDX = createMDX();
 
 /** @type {import('next').NextConfig} */
 const config = {
-  reactStrictMode: true,${!ctx.dev && siteUrl ? `\n  output: 'export',` : ""}
-  serverExternalPackages: ['mermaid'],
+  reactStrictMode: true,${outputLine}
+  serverExternalPackages: ${isOApi ? "['mermaid', 'shiki']" : "['mermaid']"},
   images: {
     unoptimized: true,
-  },${ctx.dev ? `\n  async rewrites() {\n    return [{ source: '/:path(.+)\\\\.md', destination: '/api/raw/:path' }];\n  },` : ""}
+  },${rewritesBlock}
 };
 
 export default withMDX(config);
 `;
 }
 
+//#endregion
+//#region src/core/generator/openapi.ts
+/**
+* 生成 lib/openapi.ts — OpenAPI 实例定义
+*
+* 使用绝对路径解析 spec 文件，避免 SSG 构建时相对路径失效的问题。
+* 支持多文件输入（specs 数组）和单文件（specPath 向后兼容）。
+*/
+function generateOpenApiLib(ctx) {
+	if (!isOpenApiEnabled(ctx.config)) return null;
+	const specPaths = resolveOpenApiSpecPaths(ctx.config);
+	if (specPaths.length === 0) return null;
+	return `import { createOpenAPI } from 'fumadocs-openapi/server';
+
+export const openapi = createOpenAPI({
+  input: [${specPaths.map((p) => join(ctx.projectDir, p)).map((p) => `'${p}'`).join(", ")}],
+});
+`;
+}
+/**
+* 生成 components/api-page.client.tsx — APIPage 客户端配置
+*
+* createAPIPage 的 client 参数是 APIPageClientOptions（配置对象），
+* 不是 React 组件。使用 defineClientConfig() 创建默认导出。
+*/
+function generateApiClientComponent() {
+	return `'use client';
+
+import { defineClientConfig } from 'fumadocs-openapi/ui/client';
+
+export default defineClientConfig();
+`;
+}
+/**
+* 生成 components/api-page.tsx — APIPage 服务端组件包装器
+*/
+function generateApiPageComponent() {
+	return `import { openapi } from '@/lib/openapi';
+import { createAPIPage } from 'fumadocs-openapi/ui';
+import client from './api-page.client';
+
+export const APIPage = createAPIPage(openapi, {
+  client,
+});
+`;
+}
+
 //#endregion
 //#region src/core/generator/package-json.ts
 function getOpenManualVersion() {
-	return "0.13.0";
+	return "0.14.1";
 }
 function generatePackageJson(ctx) {
 	const openmanualVersion = getOpenManualVersion();
 	let openmanualDep;
 	if (ctx.openmanualRoot && ctx.appDir) openmanualDep = `file:${relative(ctx.appDir, ctx.openmanualRoot)}`;
 	else openmanualDep = `^${openmanualVersion}`;
-	return `${JSON.stringify({
+	const pkg = {
 		name: "openmanual-app",
 		type: "module",
 		private: true,
@@ -513,13 +822,18 @@ function generatePackageJson(ctx) {
 			react: "^19.1.0",
 			"react-dom": "^19.1.0",
 			tailwindcss: "^4.1.15",
-			zod: "^4.0.0"
+			zod: "^4.0.0",
+			...isOpenApiEnabled(ctx.config) ? {
+				"fumadocs-openapi": "^10.7.1",
+				shiki: "^3.0.0"
+			} : {}
 		},
 		devDependencies: {
 			"@types/react": "^19.1.0",
 			"@types/react-dom": "^19.1.0"
 		}
-	}, null, 2)}\n`;
+	};
+	return `${JSON.stringify(pkg, null, 2)}\n`;
 }
 
 //#endregion
@@ -527,17 +841,20 @@ function generatePackageJson(ctx) {
 function generatePage(_ctx) {
 	const isStrict = _ctx.config.contentPolicy !== "all";
 	const pageActionsEnabled = _ctx.config.pageActions?.enabled !== false;
-	if (_ctx.config.i18n?.enabled === true) return generatePageI18n(_ctx, isStrict, pageActionsEnabled);
-	return generatePageSingle(_ctx, isStrict, pageActionsEnabled);
+	const isI18n = isI18nEnabled(_ctx.config);
+	const isOApi = isOpenApiEnabled(_ctx.config);
+	const allSlugs = _ctx.allSlugs ?? /* @__PURE__ */ new Set();
+	if (isI18n) return generatePageI18n(_ctx, isStrict, pageActionsEnabled, allSlugs, isOApi);
+	return generatePageSingle(_ctx, isStrict, pageActionsEnabled, allSlugs, isOApi);
 }
-function generatePageSingle(_ctx, isStrict, pageActionsEnabled) {
+function generatePageSingle(_ctx, isStrict, pageActionsEnabled, allSlugs, isOApi) {
 	const allowedSlugsSnippet = isStrict ? `
-const allowedSlugs = new Set(${JSON.stringify([...collectConfiguredSlugs(_ctx.config)])});
+const allowedSlugs = new Set<string>(${JSON.stringify([...allSlugs])});
 
 function isAllowed(slug: string[] | undefined): boolean {
   if (allowedSlugs.size === 0) return true;
-  const key = slug ? slug.join('/') : 'index';
-  return allowedSlugs.has(key);
+  const key = slug && slug.length > 0 ? slug.join('/') : 'index';
+  return allowedSlugs.has(key) || (slug?.[0] === 'openapi') || (slug?.[0] === 'api');
 }
 ` : "";
 	return `import { source } from '@/lib/source';
@@ -550,7 +867,7 @@ import { Files, File, Folder } from 'fumadocs-ui/components/files';
 import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
 import { TypeTable } from 'fumadocs-ui/components/type-table';
 import { Mermaid } from '@/components/mermaid';
-import { Callout, CalloutTitle, CalloutDescription } from '@/components/callout';${pageActionsEnabled ? "\nimport { PageActions } from '@/components/page-actions';" : ""}
+import { Callout, CalloutTitle, CalloutDescription } from '@/components/callout';${pageActionsEnabled ? "\nimport { PageActions } from '@/components/page-actions';" : ""}${isOApi ? "\nimport { APIPage } from '@/components/api-page';" : ""}
 ${allowedSlugsSnippet}
 export default async function Page({ params }: { params: Promise<{ slug?: string[] }> }) {
   const { slug } = await params;
@@ -563,7 +880,18 @@ ${isStrict ? `
   if (!page) {
     notFound();
   }
-
+${isOApi ? `
+  if (page.data.type === 'openapi') {
+    return (
+      <DocsPage full>
+        <h1 className="text-[1.75em] font-semibold">{page.data.title}</h1>
+        <DocsBody>
+          <APIPage {...(page.data as any).getAPIPageProps()} />
+        </DocsBody>
+      </DocsPage>
+    );
+  }
+` : ""}
   const MDX = page.data.body;
 
   return (
@@ -604,14 +932,15 @@ export function generateStaticParams() {
 }`}
 `;
 }
-function generatePageI18n(_ctx, isStrict, pageActionsEnabled) {
+function generatePageI18n(_ctx, isStrict, pageActionsEnabled, allSlugs, isOApi) {
 	const allowedSlugsSnippet = isStrict ? `
-const allowedSlugs = new Set(${JSON.stringify([...collectConfiguredSlugs(_ctx.config)])});
+const allowedSlugs = new Set<string>(${JSON.stringify([...allSlugs])});
 
-function isAllowed(slug: string[] | undefined): boolean {
+function isAllowed(slug: string[] | undefined, lang?: string): boolean {
   if (allowedSlugs.size === 0) return true;
-  const key = slug ? slug.join('/') : 'index';
-  return allowedSlugs.has(key);
+  const rawKey = slug && slug.length > 0 ? slug.join('/') : 'index';
+  const key = lang ? \`\${lang}/\${rawKey}\` : rawKey;
+  return allowedSlugs.has(key) || (slug?.[0] === 'openapi') || (slug?.[0] === 'api');
 }
 ` : "";
 	return `import { source } from '@/lib/source';
@@ -624,20 +953,31 @@ import { Files, File, Folder } from 'fumadocs-ui/components/files';
 import { Accordion, Accordions } from 'fumadocs-ui/components/accordion';
 import { TypeTable } from 'fumadocs-ui/components/type-table';
 import { Mermaid } from '@/components/mermaid';
-import { Callout, CalloutTitle, CalloutDescription } from '@/components/callout';${pageActionsEnabled ? "\nimport { PageActions } from '@/components/page-actions';" : ""}
+import { Callout, CalloutTitle, CalloutDescription } from '@/components/callout';${pageActionsEnabled ? "\nimport { PageActions } from '@/components/page-actions';" : ""}${isOApi ? "\nimport { APIPage } from '@/components/api-page';" : ""}
 ${allowedSlugsSnippet}
 export default async function Page({ params }: { params: Promise<{ slug?: string[]; lang: string }> }) {
   const { slug, lang } = await params;
   const page = source.getPage(slug, lang);
 ${isStrict ? `
-  if (!isAllowed(slug)) {
+  if (!isAllowed(slug, lang)) {
     notFound();
   }
 ` : ""}
   if (!page) {
     notFound();
   }
-
+${isOApi ? `
+  if (page.data.type === 'openapi') {
+    return (
+      <DocsPage full>
+        <h1 className="text-[1.75em] font-semibold">{page.data.title}</h1>
+        <DocsBody>
+          <APIPage {...(page.data as any).getAPIPageProps()} />
+        </DocsBody>
+      </DocsPage>
+    );
+  }
+` : ""}
   const MDX = page.data.body;
 
   return (
@@ -663,7 +1003,7 @@ ${pageActionsEnabled ? `      <div className="flex items-start justify-between g
 ${isStrict ? `
 export function generateStaticParams() {
   let params = source.generateParams();
-  params = params.filter((p: { slug: string[]; lang: string }) => isAllowed(p.slug));
+  params = params.filter((p: { slug: string[]; lang: string }) => isAllowed(p.slug, p.lang));
   // Ensure every language has a homepage entry (slug: [])
   const languages = [...new Set(params.map((p: { lang: string }) => p.lang))];
   for (const lang of languages) {
@@ -725,7 +1065,7 @@ export default config;
 * 一次作为生成应用的依赖）导致的多实例 React Context 问题。
 */
 function generateProvider(ctx) {
-	const searchEnabled = ctx.config.search?.enabled !== false;
+	const searchEnabled = ctx.config.search !== void 0;
 	if (ctx.config.i18n?.enabled === true) return `'use client';
 import { RootProvider } from 'fumadocs-ui/provider/next';
 import SafeSearchDialog from './components/search-dialog';
@@ -1168,6 +1508,42 @@ export default defineConfig({
 `;
 }
 
+//#endregion
+//#region src/core/generator/top-bar.ts
+function generateTopBarComponent(ctx) {
+	const { config } = ctx;
+	const header = config.header;
+	const height = header.height ?? "64px";
+	const sticky = header.sticky ?? true;
+	const bordered = header.bordered ?? true;
+	const background = header.background ?? "";
+	const logoProps = resolveNavLogoProps(header.logo ?? config.name, config.name);
+	const linksJson = JSON.stringify(header.links ?? []);
+	const backgroundProp = background ? `\n    background='${background}',` : "";
+	const isTopBarSearch = config.search?.position === "header";
+	return `'use client';
+
+import { TopBar } from 'openmanual/components/top-bar';
+import { NavLogo } from 'openmanual/components/nav-layout';
+import { NavLinks } from 'openmanual/components/nav-links';${isTopBarSearch ? "\nimport { TopBarSearchTrigger } from 'openmanual/components/top-bar-search-trigger';" : ""}
+
+const navLinks = ${linksJson};
+${isTopBarSearch ? "const searchCenter = <TopBarSearchTrigger />;" : ""}
+
+export function OmTopBar() {
+  return (
+    <TopBar
+      height='${height}'
+      sticky={${sticky}}${backgroundProp}
+      bordered={${bordered}}
+      left={<NavLogo ${logoProps} />}${isTopBarSearch ? "\n      center={searchCenter}" : ""}
+      right={<NavLinks links={navLinks} />}
+    />
+  );
+}
+`;
+}
+
 //#endregion
 //#region src/core/generator/tsconfig.ts
 function generateTsconfig() {
@@ -1208,6 +1584,44 @@ function generateTsconfig() {
 //#region src/core/generator/index.ts
 async function generateAll(ctx) {
 	const isI18n = isI18nEnabled(ctx.config);
+	if (isOpenApiEnabled(ctx.config)) {
+		const { access } = await import("node:fs/promises");
+		const { extname, join } = await import("node:path");
+		const supportedExts = [
+			".json",
+			".yaml",
+			".yml"
+		];
+		const specPaths = resolveOpenApiSpecPaths(ctx.config);
+		for (const specPath of specPaths) {
+			const absolutePath = join(ctx.projectDir, specPath);
+			const ext = extname(absolutePath).toLowerCase();
+			if (!supportedExts.includes(ext)) throw new Error(`[openapi] 不支持的 OpenAPI 规范文件格式: "${ext}"（文件: ${specPath}）。支持的格式: ${supportedExts.join(", ")}`);
+			try {
+				await access(absolutePath);
+			} catch {
+				throw new Error(`[openapi] OpenAPI 规范文件不存在: "${specPath}"。请确认 "openapi.specs" 或 "openapi.specPath" 在 openmanual.json 中配置的路径正确。`);
+			}
+		}
+	}
+	await computeAllSlugs(ctx);
+	const isOApi = isOpenApiEnabled(ctx.config);
+	const openapiFiles = [];
+	if (isOApi) {
+		const openapiLib = generateOpenApiLib(ctx);
+		if (openapiLib) openapiFiles.push({
+			path: "lib/openapi.ts",
+			content: openapiLib
+		});
+		openapiFiles.push({
+			path: "components/api-page.client.tsx",
+			content: generateApiClientComponent()
+		});
+		openapiFiles.push({
+			path: "components/api-page.tsx",
+			content: generateApiPageComponent()
+		});
+	}
 	const baseFiles = [
 		{
 			path: "source.config.ts",
@@ -1254,9 +1668,11 @@ async function generateAll(ctx) {
 			content: generatePageActionsComponent()
 		}
 	];
+	const headerEnabled = isHeaderEnabled(ctx.config);
 	let files;
 	if (isI18n) files = [
 		...baseFiles,
+		...openapiFiles,
 		{
 			path: "lib/i18n.ts",
 			content: generateI18nConfig(ctx)
@@ -1291,6 +1707,10 @@ async function generateAll(ctx) {
 			path: "app/[lang]/components/search-dialog.tsx",
 			content: generateSearchDialog(ctx)
 		},
+		...headerEnabled ? [{
+			path: "app/[lang]/components/top-bar.tsx",
+			content: generateTopBarComponent(ctx)
+		}] : [],
 		{
 			path: "app/[lang]/[[...slug]]/layout.tsx",
 			content: generateDocsLayout(ctx)
@@ -1302,6 +1722,7 @@ async function generateAll(ctx) {
 	];
 	else files = [
 		...baseFiles,
+		...openapiFiles,
 		...ctx.dev ? [{
 			path: "app/api/raw/[...path]/route.ts",
 			content: generateRawContentRoute(ctx)
@@ -1324,6 +1745,10 @@ async function generateAll(ctx) {
 			path: "app/components/search-dialog.tsx",
 			content: generateSearchDialog(ctx)
 		},
+		...headerEnabled ? [{
+			path: "app/components/top-bar.tsx",
+			content: generateTopBarComponent(ctx)
+		}] : [],
 		{
 			path: "app/[[...slug]]/layout.tsx",
 			content: generateDocsLayout(ctx)
@@ -1350,10 +1775,8 @@ async function generateAll(ctx) {
 function generateRootLayout(ctx) {
 	const { config } = ctx;
 	const favicon = config.favicon;
-	return `import { AppLayout } from 'openmanual/components/app-layout';
-import { AppProvider } from './provider';
-import type { ReactNode } from 'react';
-${favicon ? `import type { Metadata } from 'next';
+	const headerEnabled = isHeaderEnabled(config);
+	return `${favicon ? `import type { Metadata } from 'next';
 
 export const metadata: Metadata = {
   icons: {
@@ -1361,12 +1784,15 @@ export const metadata: Metadata = {
   },
 };
 
-` : ""}import '../global.css';
+` : ""}${headerEnabled ? "import { OmTopBar } from './components/top-bar';\n" : ""}import { AppLayout } from 'openmanual/components/app-layout';
+import { AppProvider } from './provider';
+import type { ReactNode } from 'react';
+import '../global.css';
 
 export default function RootLayout({ children }: { children: ReactNode }) {
   return (
     <AppLayout>
-      <AppProvider>{children}</AppProvider>
+      <AppProvider>${headerEnabled ? "<OmTopBar />\n      " : ""}{children}</AppProvider>
     </AppLayout>
   );
 }
@@ -1383,6 +1809,7 @@ export default function RootLayout({ children }: { children: ReactNode }) {
 function generateRootLayoutI18n(ctx) {
 	const { config } = ctx;
 	const favicon = config.favicon;
+	const headerEnabled = isHeaderEnabled(config);
 	return `${favicon ? `import type { Metadata } from 'next';
 
 export const metadata: Metadata = {
@@ -1391,7 +1818,7 @@ export const metadata: Metadata = {
   },
 };
 
-` : ""}import { AppLayout } from 'openmanual/components/app-layout';
+` : ""}${headerEnabled ? "import { OmTopBar } from './components/top-bar';\n" : ""}import { AppLayout } from 'openmanual/components/app-layout';
 import { AppProvider } from './provider';
 import type { ReactNode } from 'react';
 import '../../global.css';
@@ -1407,7 +1834,7 @@ export default async function RootLayout({
 
   return (
     <AppLayout lang={lang}>
-      <AppProvider lang={lang}>{children}</AppProvider>
+      <AppProvider lang={lang}>${headerEnabled ? "<OmTopBar />\n      " : ""}{children}</AppProvider>
     </AppLayout>
   );
 }
@@ -1419,6 +1846,9 @@ function generateDocsLayout(ctx) {
 	const navLinks = config.navbar?.links ?? [];
 	const footerText = config.footer?.text ?? "";
 	const isI18n = isI18nEnabled(config);
+	const isOApi = isOpenApiEnabled(config);
+	const rootGroups = ctx.rootGroups;
+	const isHeaderSearch = config.search?.position === "header";
 	const linksArray = navLinks.map((l) => ({
 		text: l.label,
 		url: l.href,
@@ -1430,6 +1860,13 @@ function generateDocsLayout(ctx) {
 	const configDesc = config.description ?? "";
 	const descLine = configDesc ? isI18n ? "" : `description: '${configDesc.replace(/'/g, "\\'")}',` : "";
 	const treeLine = isI18n ? "tree: source.getPageTree(lang)," : "tree: source.getPageTree(),";
+	const separateTab = isOpenApiEnabled(config) && isSeparateTabMode(config);
+	const openapiTab = separateTab ? {
+		title: config.openapi?.label ?? "接口文档",
+		url: isI18n ? "/${lang}/openapi" : "/openapi",
+		urls: /* @__PURE__ */ new Set()
+	} : null;
+	const sidebarTabsLine = rootGroups && rootGroups.length > 0 || openapiTab ? isI18n ? generateI18nSidebarTabs(config, rootGroups, openapiTab) : generateSingleSidebarTabs(config, rootGroups, openapiTab) : "";
 	if (isI18n) return `import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 import { baseOptions } from '@/lib/layout';
 import { source } from '@/lib/source';
@@ -1441,13 +1878,16 @@ export default async function DocsLayoutWrapper({
   params: Promise<{ lang: string }>;
   children: ReactNode;
 }) {
-  const { lang } = await params;${configDesc ? `
+  const { lang } = await params;
+${isOApi && separateTab ? `  const _omFirstApi = source.getPages(lang)?.find((p: any) => p.data?.type === 'openapi');
+  const _omApiUrl = _omFirstApi?.url ?? \`/\${lang}/openapi\`;
+` : ""}${configDesc ? `
   const indexPage = source.getPage([], lang);
   const siteDescription = indexPage?.data.description ?? configDescription;` : ""}
 
   const docsOptions = {
     ...baseOptions(lang),
-    ${treeLine}${githubLine}${linksLine}${footerLine}${configDesc ? "\n    description: siteDescription," : ""}
+    ${treeLine}${sidebarTabsLine}${githubLine}${linksLine}${footerLine}${configDesc ? "\n    description: siteDescription," : ""}${isHeaderSearch ? "\n    searchToggle: { enabled: false }," : ""}
   };
 
   return (
@@ -1460,10 +1900,13 @@ export default async function DocsLayoutWrapper({
 	return `import { DocsLayout } from 'fumadocs-ui/layouts/docs';
 import { baseOptions } from '@/lib/layout';
 import { source } from '@/lib/source';
-import type { ReactNode } from 'react';
+import type { ReactNode } from 'react';${isOApi && separateTab ? `
+const _omFirstApi = source.getPages()?.find((p: any) => p.data?.type === 'openapi');
+const _omApiUrl = _omFirstApi?.url ?? '/openapi';
+` : ""}
 const docsOptions = {
   ...baseOptions(),
-  ${treeLine}${githubLine}${linksLine}${footerLine}${descLine}
+  ${treeLine}${sidebarTabsLine}${githubLine}${linksLine}${footerLine}${descLine}${isHeaderSearch ? "\n  searchToggle: { enabled: false }," : ""}
 };
 
 export default function DocsLayoutWrapper({ children }: { children: ReactNode }) {
@@ -1475,6 +1918,37 @@ export default function DocsLayoutWrapper({ children }: { children: ReactNode })
 }
 `;
 }
+/**
+* Generate i18n sidebar.tabs string.
+* Extracted from generateDocsLayout to avoid deeply nested template literals
+* that confuse the oxc parser when escaped backticks are involved.
+*/
+function generateI18nSidebarTabs(config, rootGroups, openapiTab) {
+	const entries = (rootGroups ?? []).map((g) => ({
+		title: g.title,
+		dirPath: g.dirPath,
+		url: g.url,
+		urls: g.urls
+	}));
+	const entriesJson = JSON.stringify(entries);
+	const nameEscaped = config.name.replace(/'/g, "\\'");
+	const openapiTabLine = openapiTab ? `,\n        { title: '${openapiTab.title.replace(/'/g, "\\'")}', url: _omApiUrl, urls: new Set<string>() }` : "";
+	return `\n    sidebar: {\n      tabs: [\n        ${`{ title: '${nameEscaped}', url: \`/\${lang}\` }`},\n        ...${`(${entriesJson} as Array<{title:string;dirPath:string;url:string;urls:string[]}>).filter(g => g.dirPath.startsWith(\`\${lang}/\`)).map(g => ({ title: g.title, url: g.url, urls: new Set<string>(g.urls) }))`}${openapiTabLine}\n      ],\n    },`;
+}
+/**
+* Generate single-language (non-i18n) sidebar.tabs string.
+* Uses template literal to preserve Set<string> for urls property.
+*/
+function generateSingleSidebarTabs(config, rootGroups, openapiTab) {
+	const nameEscaped = config.name.replace(/'/g, "\\'");
+	const groupEntries = (rootGroups ?? []).map((g) => {
+		const title = g.title.replace(/'/g, "\\'");
+		const urlsArr = JSON.stringify(g.urls);
+		return `{ title: '${title}', url: '${g.url}', urls: new Set(${urlsArr}) }`;
+	}).join(",\n        ");
+	const openapiTabLine = openapiTab ? `,\n        { title: '${openapiTab.title.replace(/'/g, "\\'")}', url: _omApiUrl, urls: new Set<string>() }` : "";
+	return `\n    sidebar: {\n      tabs: [\n        { title: '${nameEscaped}', url: '/' },${groupEntries ? "\n        " + groupEntries : ""}${openapiTabLine}\n      ],\n    },`;
+}
 function generateOpenManualLogoSvg(name, variant = "light") {
 	const textColor = variant === "dark" ? "#E8E0D4" : "#000000";
 	return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 190 32" width="190" height="32">
@@ -1497,57 +1971,105 @@ async function ensureLogoFile(ctx, logoPath, variant) {
 	}
 }
 /**
-* Generate complete meta.json for each sidebar group directory.
-* Writes title, icon, defaultOpen, and pages ordering so that Fumadocs
-* can render the sidebar natively without restructureTree().
+* Generate or enrich meta.json files for each content directory.
 *
-* In dir-parser mode, generates meta.json inside each language subdirectory
-* (e.g. content/zh/guide/meta.json). In dot-parser mode, generates at the
-* group directory level with locale-suffixed files for i18n.
+* Strategy:
+* 1. If meta.json files exist → enrich missing fields (icon/defaultOpen/pages)
+* 2. If no meta.json → auto-generate from file system structure
 */
-async function generateMetaFiles(ctx) {
-	const sidebar = ctx.config.sidebar;
-	if (!sidebar || sidebar.length === 0) return;
+/**
+* Compute all slugs from meta.json files, falling back to file system scan.
+* Stores result in ctx.allSlugs for use by generatePage().
+* Also extracts root groups (meta.json with root: true) into ctx.rootGroups.
+*/
+async function computeAllSlugs(ctx) {
 	const contentAbsDir = join(ctx.projectDir, ctx.contentDir);
 	const isI18n = isI18nEnabled(ctx.config);
 	const useDirParser = isDirParser(ctx.config);
 	const languages = isI18n ? (ctx.config.i18n?.languages ?? []).map((l) => l.code) : [];
-	for (const group of sidebar) {
-		if (group.pages.every((p) => !p.slug.includes("/"))) {
-			await generateRootMetaJson(ctx, group, contentAbsDir, languages, useDirParser);
-			continue;
-		}
-		const dirPrefix = group.pages.map((p) => p.slug).find((slug) => slug.includes("/"))?.split("/")[0];
-		if (!dirPrefix) continue;
-		const metaObj = { title: group.group };
-		if (group.icon) metaObj.icon = group.icon;
-		if (group.collapsed !== void 0) metaObj.defaultOpen = !group.collapsed;
-		const pageFiles = group.pages.filter((p) => p.slug.startsWith(`${dirPrefix}/`)).map((p) => p.slug.split("/").slice(1).join("/"));
-		if (pageFiles.length > 0) metaObj.pages = pageFiles;
-		if (useDirParser) for (const lang of languages) await writeMetaIfNotExists(join(join(contentAbsDir, lang, dirPrefix), "meta.json"), metaObj);
-		else {
-			const dirPath = join(contentAbsDir, dirPrefix);
-			await writeMetaIfNotExists(join(dirPath, "meta.json"), metaObj);
-			if (isI18n) for (const lang of languages) {
-				if (lang === ctx.config.i18n?.defaultLanguage) continue;
-				await writeMetaIfNotExists(join(dirPath, `meta.${lang}.json`), metaObj);
-			}
+	const metaGroups = await scanMetaFiles(contentAbsDir, languages, useDirParser);
+	if (metaGroups.length > 0) {
+		ctx.allSlugs = collectSlugsFromMeta(metaGroups);
+		const allFiles = await scanContentDir(contentAbsDir);
+		for (const file of allFiles) if (useDirParser ? file.segments.length === 2 && languages.includes(file.segments[0]) : file.segments.length === 1) ctx.allSlugs.add(file.slug);
+		const scannedDirCache = /* @__PURE__ */ new Map();
+		for (const group of metaGroups) {
+			const dirAbsPath = join(contentAbsDir, group.dirPath);
+			try {
+				const dirFiles = await scanContentDir(dirAbsPath);
+				scannedDirCache.set(group.dirPath, dirFiles);
+				if (!group.pages || group.pages.length === 0) for (const df of dirFiles) ctx.allSlugs.add(`${group.dirPath}/${df.slug}`);
+			} catch {}
 		}
+		ctx.rootGroups = metaGroups.filter((g) => g.root === true).map((g) => {
+			const cached = scannedDirCache.get(g.dirPath);
+			const firstPage = g.pages?.[0] ?? cached?.[0]?.name ?? "index";
+			const allUrls = (cached ?? []).map((f) => `/${g.dirPath}/${f.name}`);
+			return {
+				title: g.title,
+				dirPath: g.dirPath,
+				url: `/${g.dirPath}/${firstPage}`,
+				urls: allUrls
+			};
+		});
+		return;
+	}
+	const files = await scanContentDir(contentAbsDir);
+	ctx.allSlugs = new Set(files.map((f) => f.slug));
+}
+async function generateMetaFiles(ctx) {
+	const contentAbsDir = join(ctx.projectDir, ctx.contentDir);
+	const isI18n = isI18nEnabled(ctx.config);
+	const useDirParser = isDirParser(ctx.config);
+	const languages = isI18n ? (ctx.config.i18n?.languages ?? []).map((l) => l.code) : [];
+	const metaGroups = await scanMetaFiles(contentAbsDir, languages, useDirParser);
+	if (metaGroups.length > 0) {
+		for (const group of metaGroups) await enrichMetaFile(group);
+		return;
 	}
-	await injectPageFrontmatter(ctx);
+	await autoGenerateMetaFromFS(ctx, contentAbsDir, languages, useDirParser);
 }
 /**
-* Generate meta.json for root-level page groups (pages without directory prefix).
-* Writes to content/{lang}/meta.json (dir-parser) or content/meta.json (dot-parser).
+* Validate an existing meta.json file is readable.
+* Does NOT modify the file — all user-set fields (including "root") are preserved as-is.
+* Fumadocs reads meta.json directly via its own content source pipeline.
 */
-async function generateRootMetaJson(_ctx, group, contentAbsDir, languages, useDirParser) {
-	const metaObj = { title: group.group };
-	if (group.icon) metaObj.icon = group.icon;
-	if (group.collapsed !== void 0) metaObj.defaultOpen = !group.collapsed;
-	const pageFiles = group.pages.map((p) => p.slug);
-	if (pageFiles.length > 0) metaObj.pages = pageFiles;
-	if (useDirParser) for (const lang of languages) await writeMetaIfNotExists(join(contentAbsDir, lang, "meta.json"), metaObj);
-	else await writeMetaIfNotExists(join(contentAbsDir, "meta.json"), metaObj);
+async function enrichMetaFile(_group) {
+	try {
+		await readFile(_group.filePath, "utf-8");
+	} catch {}
+}
+/**
+* Auto-generate meta.json files from the file system structure.
+* Used when no meta.json and no sidebar config exist.
+*/
+async function autoGenerateMetaFromFS(_ctx, contentAbsDir, languages, useDirParser) {
+	const files = await scanContentDir(contentAbsDir);
+	const rootFiles = [];
+	const dirGroups = /* @__PURE__ */ new Map();
+	for (const file of files) if (file.segments.length <= 1) rootFiles.push(file);
+	else {
+		const dirName = file.segments[0];
+		if (dirName === void 0) continue;
+		if (!dirGroups.has(dirName)) dirGroups.set(dirName, []);
+		dirGroups.get(dirName)?.push(file);
+	}
+	if (rootFiles.length > 0) {
+		const rootMeta = {
+			title: "Getting Started",
+			pages: rootFiles.map((f) => f.name)
+		};
+		if (useDirParser) for (const lang of languages) await writeMetaIfNotExists(join(contentAbsDir, lang, "meta.json"), rootMeta);
+		else await writeMetaIfNotExists(join(contentAbsDir, "meta.json"), rootMeta);
+	}
+	for (const [dirName, dirFiles] of dirGroups) {
+		const dirMeta = {
+			title: formatTitle(dirName),
+			pages: dirFiles.map((f) => f.segments.slice(1).join("/"))
+		};
+		if (useDirParser) for (const lang of languages) await writeMetaIfNotExists(join(contentAbsDir, lang, dirName, "meta.json"), dirMeta);
+		else await writeMetaIfNotExists(join(contentAbsDir, dirName, "meta.json"), dirMeta);
+	}
 }
 /**
 * Write meta.json only if it does not already exist (preserve user edits).
@@ -1560,62 +2082,6 @@ async function writeMetaIfNotExists(filePath, data) {
 		await writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
 	}
 }
-/**
-* Inject page-level title and icon from sidebar config into each .mdx file's frontmatter.
-* Uses upsert semantics: only writes fields that are missing from existing frontmatter.
-*/
-async function injectPageFrontmatter(ctx) {
-	const sidebar = ctx.config.sidebar;
-	if (!sidebar) return;
-	const contentAbsDir = join(ctx.projectDir, ctx.contentDir);
-	const useDirParser = isDirParser(ctx.config);
-	const languages = isI18nEnabled(ctx.config) ? (ctx.config.i18n?.languages ?? []).map((l) => l.code) : [];
-	for (const group of sidebar) for (const page of group.pages) {
-		const fieldsToInject = {};
-		if (page.title) fieldsToInject.title = page.title;
-		if (page.icon) fieldsToInject.icon = page.icon;
-		if (Object.keys(fieldsToInject).length === 0) continue;
-		const targets = resolveMdxPaths(contentAbsDir, page.slug, useDirParser, languages);
-		for (const mdxPath of targets) try {
-			const content = await readFile(mdxPath, "utf-8");
-			const updated = upsertFrontmatter(content, fieldsToInject);
-			if (updated !== content) await writeFile(mdxPath, updated, "utf-8");
-		} catch {}
-	}
-}
-/**
-* Resolve .mdx file paths for a given slug across all applicable locales.
-*/
-function resolveMdxPaths(contentAbsDir, slug, useDirParser, languages) {
-	if (useDirParser) return languages.map((lang) => join(contentAbsDir, lang, `${slug}.mdx`));
-	return [join(contentAbsDir, `${slug}.mdx`)];
-}
-/**
-* Upsert fields into MDX frontmatter. Only adds missing fields; never overwrites existing ones.
-*
-* Handles:
-* - No frontmatter → creates one with the injected fields
-* - Existing frontmatter missing some fields → adds only the missing ones
-* - All fields already present → returns original content unchanged
-*/
-function upsertFrontmatter(content, fields) {
-	const match = content.match(/^---\r?\n([\s\S]*?)\r?\n---/);
-	if (!match) return `---\n${Object.entries(fields).map(([key, value]) => `${key}: ${value}`).join("\n")}\n---\n\n${content}`;
-	const existingLines = (match[1] ?? "").split("\n");
-	const existingKeys = /* @__PURE__ */ new Set();
-	for (const line of existingLines) {
-		const trimmed = line.trim();
-		if (trimmed && !trimmed.startsWith("#")) {
-			const keyMatch = trimmed.match(/^(\w[\w-]*)\s*:/);
-			if (keyMatch?.[1]) existingKeys.add(keyMatch[1]);
-		}
-	}
-	const newFields = Object.entries(fields).filter(([key]) => !existingKeys.has(key));
-	if (newFields.length === 0) return content;
-	const newFieldLines = newFields.map(([key, value]) => `${key}: ${value}`).join("\n");
-	const insertionPoint = (match.index ?? 0) + match[0].length - 3;
-	return content.slice(0, insertionPoint) + "\n" + newFieldLines + "\n" + content.slice(insertionPoint);
-}
 
 //#endregion
 //#region src/utils/install-deps.ts
@@ -2070,7 +2536,7 @@ const regenerateCommand = new Command("_regenerate").description("内部命令
 //#endregion
 //#region src/cli/bin.ts
 function getVersion() {
-	return "0.13.0";
+	return "0.14.1";
 }
 const program = new Command();
 const commandName = basename(process.argv[1] ?? "openmanual");