openmanual 0.12.0 → 0.14.0

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,30 +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 buildTitleMap(config) {
-	const map = {};
-	if (config.sidebar) for (const group of config.sidebar) for (const page of group.pages) map[page.slug] = page.title;
-	return map;
-}
 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
@@ -98,7 +158,6 @@ const DEFAULT_CONFIG = {
 		primaryHue: 213,
 		darkMode: true
 	},
-	search: { enabled: true },
 	mdx: {},
 	pageActions: { enabled: true }
 };
@@ -144,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
@@ -161,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() {
@@ -178,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};
 
@@ -238,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%);
@@ -266,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 {
@@ -359,17 +547,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';
@@ -399,7 +595,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';
 
@@ -467,34 +714,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.12.0";
+	return "0.14.0";
 }
 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,
@@ -518,13 +815,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
@@ -532,17 +834,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';
@@ -555,7 +860,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;
@@ -568,7 +873,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 (
@@ -609,14 +925,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';
@@ -629,20 +946,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 (
@@ -668,7 +996,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) {
@@ -730,7 +1058,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';
@@ -1150,76 +1478,11 @@ export const { staticGET: GET } = createFromSource(source);
 //#endregion
 //#region src/core/generator/source-config.ts
 function generateSourceConfig(_ctx) {
-	const titleMap = buildTitleMap(_ctx.config);
-	const titleMapEntries = Object.entries(titleMap).map(([slug, title]) => `  '${slug}': '${title.replace(/'/g, "\\'")}'`).join(",\n");
-	const titleMapStr = titleMapEntries ? `{\n${titleMapEntries}\n}` : "{}";
-	const isStrict = _ctx.config.contentPolicy !== "all";
-	const isI18n = isI18nEnabled(_ctx.config);
-	const useDirParser = isDirParser(_ctx.config);
 	return `import { defineDocs, defineConfig } from 'fumadocs-mdx/config';
 import { remarkMdxMermaid } from 'fumadocs-core/mdx-plugins';
-import { z } from 'zod';
-
-const titleMap: Record<string, string> = ${titleMapStr};${isStrict ? `
-
-const allowedSlugs = new Set(${JSON.stringify([...collectConfiguredSlugs(_ctx.config)])});
-
-function slugFromPath(path: string): string {
-  const normalized = path.replace(/\\\\/g, '/');
-  const idx = normalized.indexOf('content/');
-  const relative = idx >= 0 ? normalized.slice(idx + 'content/'.length) : normalized;${useDirParser ? `
-  // dir parser: 剥离语言目录前缀 content/en/guide/configuration.mdx -> guide/configuration
-  const parts = relative.split('/');
-  if (parts.length > 1 && /^[a-z]{2}(-[A-Z]{2})?$/i.test(parts[0])) {
-    return parts.slice(1).join('/').replace(/\\.(md|mdx)$/i, '');
-  }
-  return relative.replace(/\\.(md|mdx)$/i, '');` : `
-  let slug = relative.replace(/\\.(md|mdx)$/i, '');
-${isI18n ? `  // 剥离语言后缀：index.en -> index
-  slug = slug.replace(/\\.([a-z]{2}(-[A-Z]{2})?)$/, '');` : ""}
-  return slug;`}
-}` : ""}
-function titleFromPath(path: string): string {
-${useDirParser ? `  const normalized = path.replace(/\\\\/g, '/');
-  const idx = normalized.indexOf('content/');
-  const relative = idx >= 0 ? normalized.slice(idx + 'content/'.length) : normalized;
-  // dir parser: 剥离语言目录前缀 content/en/guide/configuration.mdx -> guide/configuration
-  const parts = relative.split('/');
-  if (parts.length > 1 && /^[a-z]{2}(-[A-Z]{2})?$/i.test(parts[0])) {
-    const slug = parts.slice(1).join('/').replace(/\\.(md|mdx)$/i, '');
-    return titleMap[slug] || slug.split('/').pop() || slug;
-  }
-  const slug = relative.replace(/\\.(md|mdx)$/i, '');
-  return titleMap[slug] || slug.split('/').pop() || slug;` : `  const normalized = path.replace(/\\\\/g, '/');
-  const idx = normalized.indexOf('content/');
-  const relative = idx >= 0 ? normalized.slice(idx + 'content/'.length) : normalized;
-  let slug = relative.replace(/\\.(md|mdx)$/i, '');
-${isI18n ? `  // 剥离语言后缀：guide/configuration.en -> guide/configuration
-  slug = slug.replace(/\\.([a-z]{2}(-[A-Z]{2})?)$/, '');` : ""}
-  return titleMap[slug] || slug.split('/').pop() || slug;`}
-}
 
 export const docs = defineDocs({
   dir: 'content',
-  docs: {
-    schema: (ctx) =>
-      z.object({
-        title: z.string().optional(),
-        description: z.string().optional(),
-        icon: z.string().optional(),
-        full: z.boolean().optional(),
-      }).transform((data) => ({
-        ...data,
-        title: data.title ?? titleFromPath(ctx.path),
-      }))${isStrict ? `
-      .refine((_data) => {
-        const slug = slugFromPath(ctx.path);
-        if (allowedSlugs.size > 0 && !allowedSlugs.has(slug)) {
-          return false;
-        }
-        return true;
-      })` : ""},
-  },
 });
 
 export default defineConfig({
@@ -1238,6 +1501,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() {
@@ -1278,6 +1577,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",
@@ -1324,9 +1661,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)
@@ -1361,6 +1700,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)
@@ -1372,6 +1715,7 @@ async function generateAll(ctx) {
 	];
 	else files = [
 		...baseFiles,
+		...openapiFiles,
 		...ctx.dev ? [{
 			path: "app/api/raw/[...path]/route.ts",
 			content: generateRawContentRoute(ctx)
@@ -1394,6 +1738,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)
@@ -1420,10 +1768,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: {
@@ -1431,12 +1777,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>
   );
 }
@@ -1453,6 +1802,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 = {
@@ -1461,7 +1811,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';
@@ -1477,7 +1827,7 @@ export default async function RootLayout({
 
   return (
     <AppLayout lang={lang}>
-      <AppProvider lang={lang}>{children}</AppProvider>
+      <AppProvider lang={lang}>${headerEnabled ? "<OmTopBar />\n      " : ""}{children}</AppProvider>
     </AppLayout>
   );
 }
@@ -1489,6 +1839,8 @@ 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 linksArray = navLinks.map((l) => ({
 		text: l.label,
 		url: l.href,
@@ -1497,36 +1849,20 @@ function generateDocsLayout(ctx) {
 	const githubLine = githubLink ? `\n    github: '${githubLink}',` : "";
 	const linksLine = linksArray.length > 0 ? `\n    links: ${JSON.stringify(linksArray)},` : "";
 	const footerLine = footerText ? `\n  footer: { children: '${footerText.replace(/'/g, "\\'")}' },` : "";
-	const sidebar = config.sidebar;
-	const hasSidebar = sidebar && sidebar.length > 0;
-	const iconNames = /* @__PURE__ */ new Set();
-	if (hasSidebar) for (const g of sidebar ?? []) {
-		if (g.icon) iconNames.add(g.icon);
-		for (const p of g.pages) if (p.icon) iconNames.add(p.icon);
-	}
-	const hasIcons = iconNames.size > 0;
-	const iconNameList = [...iconNames];
-	const sidebarConfigSnippet = hasSidebar ? `\nconst sidebarConfig = ${JSON.stringify((sidebar ?? []).map((g) => ({
-		group: g.group,
-		icon: g.icon,
-		collapsed: g.collapsed,
-		pages: g.pages.map((p) => ({
-			slug: p.slug,
-			icon: p.icon
-		}))
-	})), null, 2)} as const;
-` : "";
-	const lucideImportLine = hasIcons ? `\nimport { ${iconNameList.join(", ")} } from 'lucide-react';` : "";
-	const iconMapSnippet = hasIcons ? `\nconst iconMap = {${iconNameList.map((name) => `\n  ${name}: <${name} />,`).join("")}\n} as const;
-` : "";
-	const treeLine = hasSidebar ? hasIcons ? isI18n ? "tree: restructureTree(source.getPageTree(lang), sidebarConfig, iconMap)," : "tree: restructureTree(source.getPageTree(), sidebarConfig, iconMap)," : isI18n ? "tree: restructureTree(source.getPageTree(lang), sidebarConfig)," : "tree: restructureTree(source.getPageTree(), sidebarConfig)," : isI18n ? "tree: source.getPageTree(lang)," : "tree: source.getPageTree(),";
-	const restructureTreeImport = hasSidebar ? "\nimport { restructureTree } from 'openmanual/utils/restructure-tree';" : "";
+	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';
-import type { ReactNode } from 'react';${restructureTreeImport}${lucideImportLine}
-${sidebarConfigSnippet}${iconMapSnippet}
-
+import type { ReactNode } from 'react';${configDesc ? `\nconst configDescription = '${configDesc.replace(/'/g, "\\'")}' as const;\n` : ""}
 export default async function DocsLayoutWrapper({
   params,
   children,
@@ -1535,10 +1871,15 @@ export default async function DocsLayoutWrapper({
   children: ReactNode;
 }) {
   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}
+    ${treeLine}${sidebarTabsLine}${githubLine}${linksLine}${footerLine}${configDesc ? "\n    description: siteDescription," : ""}
   };
 
   return (
@@ -1551,11 +1892,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';${restructureTreeImport}${lucideImportLine}
-${sidebarConfigSnippet}${iconMapSnippet}
+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}
+  ${treeLine}${sidebarTabsLine}${githubLine}${linksLine}${footerLine}${descLine}
 };
 
 export default function DocsLayoutWrapper({ children }: { children: ReactNode }) {
@@ -1567,6 +1910,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">
@@ -1589,34 +1963,115 @@ async function ensureLogoFile(ctx, logoPath, variant) {
 	}
 }
 /**
-* Generate meta.json (and meta.en.json in i18n mode) for each sidebar
-* group directory so that fumadocs displays the configured group name.
+* Generate or enrich meta.json files for each content directory.
+*
+* Strategy:
+* 1. If meta.json files exist → enrich missing fields (icon/defaultOpen/pages)
+* 2. If no meta.json → auto-generate from file system structure
+*/
+/**
+* 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 generateMetaFiles(ctx) {
-	const sidebar = ctx.config.sidebar;
-	if (!sidebar || sidebar.length === 0) return;
+async function computeAllSlugs(ctx) {
 	const contentAbsDir = join(ctx.projectDir, ctx.contentDir);
 	const isI18n = isI18nEnabled(ctx.config);
-	for (const group of sidebar) {
-		const dirPrefix = group.pages.map((p) => p.slug).find((slug) => slug.includes("/"))?.split("/")[0];
-		if (!dirPrefix) continue;
-		const dirPath = join(contentAbsDir, dirPrefix);
-		const metaPath = join(dirPath, "meta.json");
-		try {
-			await access(metaPath);
-		} catch {
-			await mkdir(dirPath, { recursive: true });
-			await writeFile(metaPath, `${JSON.stringify({ title: group.group }, null, 2)}\n`, "utf-8");
-		}
-		if (isI18n) {
-			const metaEnPath = join(dirPath, "meta.en.json");
+	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) {
+		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 {
-				await access(metaEnPath);
-			} catch {
-				await mkdir(dirPath, { recursive: true });
-				await writeFile(metaEnPath, `${JSON.stringify({ title: group.group }, null, 2)}\n`, "utf-8");
-			}
+				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 autoGenerateMetaFromFS(ctx, contentAbsDir, languages, useDirParser);
+}
+/**
+* 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 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).
+*/
+async function writeMetaIfNotExists(filePath, data) {
+	try {
+		await access(filePath);
+	} catch {
+		await mkdir(join(filePath, ".."), { recursive: true });
+		await writeFile(filePath, `${JSON.stringify(data, null, 2)}\n`, "utf-8");
 	}
 }
 
@@ -2073,7 +2528,7 @@ const regenerateCommand = new Command("_regenerate").description("内部命令
 //#endregion
 //#region src/cli/bin.ts
 function getVersion() {
-	return "0.12.0";
+	return "0.14.0";
 }
 const program = new Command();
 const commandName = basename(process.argv[1] ?? "openmanual");