mn-docs-mcp 0.6.2 → 1.1.0

package/src/app/[[...slug]]/page.tsx

@@ -0,0 +1,259 @@
+import { notFound } from 'next/navigation';
+import defaultMdxComponents from 'fumadocs-ui/mdx';
+import { DocsBody, DocsDescription, DocsPage, DocsTitle } from 'fumadocs-ui/layouts/docs/page';
+import { DocsLayout } from 'fumadocs-ui/layouts/docs';
+import type { Root, Folder, Item } from 'fumadocs-core/page-tree';
+import { source } from '@/src/lib/source';
+import { JsbApiFooter } from '@/src/components/JsbApiFooter';
+
+import {
+	BookOpen,
+	Code2,
+	TerminalSquare,
+	Wrench,
+	ArrowRight,
+	Sparkles,
+	Library,
+	Compass,
+} from 'lucide-react';
+import Link from 'next/link';
+
+type PageProps = {
+	params: Promise<{
+		slug?: string[];
+	}>;
+};
+
+function filterPageTree(tree: Root, slug: string[]): Root {
+	const section = slug[0];
+	const folder = tree.children.find(
+		(child): child is Folder =>
+			child.type === 'folder' &&
+			child.children.some(
+				(item): item is Item =>
+					item.type === 'page' && item.url.startsWith(`/${section}/`),
+			),
+	);
+
+	if (folder) return { ...tree, children: [folder] };
+
+	const page = tree.children.find(
+		(child): child is Item =>
+			child.type === 'page' && child.url === `/${section}`,
+	);
+
+	if (page) return { ...tree, children: [page] };
+
+	return tree;
+}
+
+function HomePage() {
+	return (
+		<div className="relative min-h-screen overflow-hidden bg-fd-background flex flex-col">
+			<div className="absolute inset-0 z-0 h-full w-full bg-[radial-gradient(#e5e7eb_1px,transparent_1px)] [background-size:16px_16px] [mask-image:radial-gradient(ellipse_50%_50%_at_50%_0%,#000_70%,transparent_100%)] dark:bg-[radial-gradient(#374151_1px,transparent_1px)]" />
+			<div className="absolute left-1/2 top-0 z-0 -ml-[40rem] h-[40rem] w-[80rem] rounded-full bg-gradient-to-b from-blue-500/10 to-transparent blur-[100px] dark:from-blue-600/10" />
+
+			<main className="relative z-10 flex-1">
+				{/* Hero */}
+				<section className="mx-auto flex max-w-5xl flex-col items-center px-6 pt-32 pb-24 text-center md:pt-40">
+					<div className="animate-in fade-in slide-in-from-bottom-4 duration-700 mb-6 inline-flex items-center gap-2 rounded-full border border-fd-border bg-fd-card/50 px-3 py-1 text-sm font-medium text-fd-muted-foreground backdrop-blur-md">
+						<Sparkles className="h-4 w-4 text-blue-500" />
+						<span>MarginNote 插件开发指南全新上线</span>
+					</div>
+
+					<h1 className="animate-in fade-in slide-in-from-bottom-6 duration-1000 text-balance text-5xl font-extrabold tracking-tight md:text-7xl">
+						构建强大的 <br className="md:hidden" />
+						<span className="bg-gradient-to-br from-blue-500 via-indigo-500 to-purple-600 bg-clip-text text-transparent drop-shadow-sm">
+							MarginNote 插件
+						</span>
+					</h1>
+
+					<p className="animate-in fade-in slide-in-from-bottom-8 duration-1000 mx-auto mt-6 max-w-2xl text-balance text-lg text-fd-muted-foreground md:text-xl">
+						探索完整的 API 参考、渐进式教程与 Cookbook 配方，赋予 MarginNote 前所未有的生产力与可能性。
+					</p>
+
+					<div className="animate-in fade-in slide-in-from-bottom-10 duration-1000 mt-10 flex flex-col items-center gap-4 sm:flex-row sm:gap-6">
+						<Link
+							href="/guides/getting-started/"
+							className="group relative inline-flex h-12 items-center justify-center gap-2 overflow-hidden rounded-full bg-fd-foreground px-8 text-base font-semibold text-fd-background transition-all hover:scale-105 hover:shadow-xl hover:shadow-fd-foreground/10 active:scale-95"
+						>
+							快速开始
+							<ArrowRight className="h-4 w-4 transition-transform group-hover:translate-x-1" />
+						</Link>
+						<Link
+							href="/reference/global/jsb/"
+							className="inline-flex h-12 items-center justify-center gap-2 rounded-full border border-fd-border bg-fd-card/50 px-8 text-base font-medium text-fd-foreground backdrop-blur-md transition-all hover:bg-fd-accent hover:text-fd-accent-foreground active:scale-95"
+						>
+							<TerminalSquare className="h-4 w-4" />
+							浏览 API 参考
+						</Link>
+					</div>
+				</section>
+
+				{/* Bento Grid */}
+				<section className="mx-auto max-w-5xl px-6 pb-32">
+					<div className="mb-12 flex items-center justify-between">
+						<h2 className="text-2xl font-bold tracking-tight text-fd-foreground">
+							探索文档
+						</h2>
+					</div>
+
+					<div className="grid grid-cols-1 gap-4 md:grid-cols-3 md:grid-rows-2">
+						{/* 教程 (占2列) */}
+						<Link
+							href="/guides/lifecycle-and-window/"
+							className="group relative col-span-1 flex flex-col justify-between overflow-hidden rounded-3xl border border-fd-border bg-gradient-to-br from-fd-card to-fd-card/50 p-8 transition-all hover:border-blue-500/50 hover:shadow-2xl hover:shadow-blue-500/10 md:col-span-2"
+						>
+							<div className="absolute right-0 top-0 -mt-8 -mr-8 h-40 w-40 rounded-full bg-blue-500/10 blur-3xl transition-all group-hover:bg-blue-500/20" />
+							<div>
+								<div className="mb-4 inline-flex rounded-xl bg-blue-500/10 p-3 text-blue-500">
+									<Compass className="h-6 w-6" />
+								</div>
+								<h3 className="mb-2 text-xl font-bold text-fd-foreground">
+									核心教程与生命周期
+								</h3>
+								<p className="text-fd-muted-foreground">
+									按合理的学习路径，全面掌握插件的生命周期、窗口管理、笔记与数据库操作等核心概念。
+								</p>
+							</div>
+							<div className="mt-8 flex items-center text-sm font-semibold text-blue-500">
+								开始学习{' '}
+								<ArrowRight className="ml-1 h-4 w-4 transition-transform group-hover:translate-x-1" />
+							</div>
+						</Link>
+
+						{/* API 参考 */}
+						<Link
+							href="/reference/global/jsb/"
+							className="group relative col-span-1 flex flex-col justify-between overflow-hidden rounded-3xl border border-fd-border bg-fd-card p-8 transition-all hover:border-purple-500/50 hover:shadow-2xl hover:shadow-purple-500/10"
+						>
+							<div>
+								<div className="mb-4 inline-flex rounded-xl bg-purple-500/10 p-3 text-purple-500">
+									<BookOpen className="h-6 w-6" />
+								</div>
+								<h3 className="mb-2 text-xl font-bold text-fd-foreground">
+									API 参考
+								</h3>
+								<p className="text-sm text-fd-muted-foreground">
+									查阅全局对象与核心 API 的完整技术说明。
+								</p>
+							</div>
+						</Link>
+
+						{/* LibMN */}
+						<Link
+							href="/libmn/"
+							className="group relative col-span-1 flex flex-col justify-between overflow-hidden rounded-3xl border border-fd-border bg-fd-card p-8 transition-all hover:border-indigo-500/50 hover:shadow-2xl hover:shadow-indigo-500/10"
+						>
+							<div>
+								<div className="mb-4 inline-flex rounded-xl bg-indigo-500/10 p-3 text-indigo-500">
+									<Library className="h-6 w-6" />
+								</div>
+								<h3 className="mb-2 text-xl font-bold text-fd-foreground">
+									LibMN 运行时
+								</h3>
+								<p className="text-sm text-fd-muted-foreground">
+									深入了解 LibMN 运行时与插件开发的核心底层模块。
+								</p>
+							</div>
+						</Link>
+
+						{/* Cookbook (占2列) */}
+						<Link
+							href="/cookbook/batch-rename-notes/"
+							className="group relative col-span-1 flex flex-col justify-between overflow-hidden rounded-3xl border border-fd-border bg-fd-card p-8 transition-all hover:border-emerald-500/50 hover:shadow-2xl hover:shadow-emerald-500/10 md:col-span-2"
+						>
+							<div className="absolute right-0 top-0 -mt-8 -mr-8 h-40 w-40 rounded-full bg-emerald-500/10 blur-3xl transition-all group-hover:bg-emerald-500/20" />
+							<div>
+								<div className="mb-4 flex items-center gap-4">
+									<div className="inline-flex rounded-xl bg-emerald-500/10 p-3 text-emerald-500">
+										<Code2 className="h-6 w-6" />
+									</div>
+									<div className="inline-flex rounded-full border border-fd-border bg-fd-background/50 px-3 py-1 text-xs font-medium text-fd-muted-foreground backdrop-blur-md">
+										开箱即用
+									</div>
+								</div>
+								<h3 className="mb-2 text-xl font-bold text-fd-foreground">
+									Cookbook 实践配方
+								</h3>
+								<p className="text-fd-muted-foreground">
+									按任务查找完整、可运行的代码片段。从批量重命名笔记到自定义脑图节点，直接复制并在你的项目中运行。
+								</p>
+							</div>
+						</Link>
+					</div>
+				</section>
+
+				{/* Bottom CTA */}
+				<section className="relative overflow-hidden border-t border-fd-border bg-fd-card/50">
+					<div className="absolute inset-0 bg-[radial-gradient(circle_at_center,var(--tw-gradient-stops))] from-blue-500/5 via-transparent to-transparent" />
+					<div className="relative mx-auto max-w-4xl px-6 py-24 text-center">
+						<Wrench className="mx-auto mb-6 h-12 w-12 text-fd-muted-foreground/50" />
+						<h2 className="text-3xl font-bold tracking-tight text-fd-foreground sm:text-4xl">
+							准备好开发你的第一个插件了吗？
+						</h2>
+						<p className="mx-auto mt-4 max-w-xl text-lg text-fd-muted-foreground">
+							跟随我们的快速指南，只需几分钟，即可在 MarginNote 中创建并运行属于你的自定义插件。
+						</p>
+						<div className="mt-8 flex items-center justify-center gap-4">
+							<Link
+								href="/guides/getting-started/"
+								className="inline-flex h-12 items-center justify-center rounded-xl bg-fd-primary px-8 text-sm font-semibold text-fd-primary-foreground shadow-sm transition-all hover:brightness-110 active:scale-95"
+							>
+								立即开始
+							</Link>
+							<Link
+								href="/contributing/"
+								className="inline-flex h-12 items-center justify-center rounded-xl border border-fd-border bg-transparent px-8 text-sm font-medium text-fd-foreground transition-all hover:bg-fd-accent active:scale-95"
+							>
+								参与贡献
+							</Link>
+						</div>
+					</div>
+				</section>
+			</main>
+		</div>
+	);
+}
+
+export default async function Page({ params }: PageProps) {
+	const { slug = [] } = await params;
+	const page = source.getPage(slug);
+	if (!page) notFound();
+
+	const Mdx = page.data.body;
+
+	if (slug.length === 0) {
+		return <HomePage />;
+	}
+
+	const tree = filterPageTree(source.pageTree, slug);
+
+	return (
+		<DocsLayout tree={tree}>
+			<DocsPage toc={page.data.toc}>
+				<DocsTitle>{page.data.title}</DocsTitle>
+				<DocsDescription>{page.data.description}</DocsDescription>
+				<DocsBody>
+					<Mdx components={defaultMdxComponents} />
+					<JsbApiFooter slug={page.slugs.join('/')} title={page.data.title} />
+				</DocsBody>
+			</DocsPage>
+		</DocsLayout>
+	);
+}
+
+export function generateStaticParams() {
+	return source.generateParams();
+}
+
+export async function generateMetadata({ params }: PageProps) {
+	const { slug = [] } = await params;
+	const page = source.getPage(slug);
+	if (!page) notFound();
+
+	return {
+		title: page.data.title,
+		description: page.data.description,
+	};
+}

package/src/app/api/search/route.ts

@@ -0,0 +1,6 @@
+import { source } from '@/src/lib/source';
+import { createFromSource } from 'fumadocs-core/search/server';
+
+export const revalidate = false;
+
+export const GET = createFromSource(source).staticGET;

package/src/app/global.css

@@ -0,0 +1,81 @@
+@import 'fumadocs-ui/css/style.css';
+
+@source '../**/*.{ts,tsx,md,mdx}';
+
+:root {
+	color-scheme: light dark;
+}
+
+.prose table {
+	display: table;
+	overflow: visible;
+	width: 100%;
+	table-layout: fixed;
+}
+
+.prose table:has(> thead > tr > :nth-child(2)):not(:has(> thead > tr > :nth-child(3))) {
+	--mn-table-cols: 2;
+}
+
+.prose table:has(> thead > tr > :nth-child(3)):not(:has(> thead > tr > :nth-child(4))) {
+	--mn-table-cols: 3;
+}
+
+.prose table:has(> thead > tr > :nth-child(4)):not(:has(> thead > tr > :nth-child(5))) {
+	--mn-table-cols: 4;
+}
+
+.prose table:has(> thead > tr > :nth-child(5)):not(:has(> thead > tr > :nth-child(6))) {
+	--mn-table-cols: 5;
+}
+
+.prose table:has(> thead > tr > :nth-child(6)):not(:has(> thead > tr > :nth-child(7))) {
+	--mn-table-cols: 6;
+}
+
+.prose table:has(> thead > tr > :nth-child(2)) :is(th, td) {
+	width: calc(100% / var(--mn-table-cols));
+	max-width: 50%;
+}
+
+.prose :is(th, td),
+.prose :is(th, td) code {
+	white-space: normal;
+	overflow-wrap: anywhere;
+	word-break: break-word;
+}
+
+.jsb-api {
+	margin-top: 2rem;
+}
+
+.jsb-api__details {
+	border: 1px solid var(--color-fd-border);
+	border-radius: 0.75rem;
+	padding: 0.75rem 1rem;
+	background: color-mix(in srgb, var(--color-fd-muted), transparent 38%);
+}
+
+.jsb-api__summary {
+	cursor: pointer;
+	font-weight: 600;
+}
+
+.jsb-api__meta {
+	margin-top: 0.75rem;
+	color: var(--color-fd-muted-foreground);
+	font-size: 0.875rem;
+}
+
+.jsb-api__meta code {
+	word-break: break-all;
+}
+
+.jsb-api ul {
+	margin-top: 0.5rem;
+}
+
+.jsb-api table {
+	margin-top: 0.75rem;
+	width: 100%;
+}

package/src/app/layout.tsx

@@ -0,0 +1,33 @@
+import type { Metadata } from 'next';
+import { RootProvider } from 'fumadocs-ui/provider/next';
+import { HomeLayout } from 'fumadocs-ui/layouts/home';
+import { baseOptions } from '@/src/lib/layout';
+import type { ReactNode } from 'react';
+import './global.css';
+
+export const metadata: Metadata = {
+	title: {
+		default: 'MarginNote插件开发文档',
+		template: '%s | MarginNote插件开发文档',
+	},
+	description: 'MarginNote插件开发的完整API参考与渐进式教程。',
+	metadataBase: new URL('https://mn-docs.museday.top'),
+};
+
+export default function RootLayout({ children }: { children: ReactNode }) {
+	return (
+		<html lang="zh-CN" suppressHydrationWarning>
+			<body>
+				<RootProvider
+					search={{
+						options: {
+							type: 'static',
+						},
+					}}
+				>
+					<HomeLayout {...baseOptions}>{children}</HomeLayout>
+				</RootProvider>
+			</body>
+		</html>
+	);
+}

package/src/components/JsbApiFooter.tsx

@@ -0,0 +1,251 @@
+'use client';
+
+import { useEffect, useMemo, useState } from 'react';
+
+type JsbApi = {
+	protocol: string;
+	properties: string[];
+	instance_methods: string[];
+	class_methods: string[];
+	export_aliases: Record<string, string>;
+};
+
+type PageConfig = {
+	protocol: string;
+	only?: Array<'properties' | 'class' | 'instance' | 'aliases'>;
+};
+
+const GLOBAL_PAGE_PROTOCOL_MAP: Record<string, PageConfig> = {
+	'reference/global/application': { protocol: 'JSBApplication' },
+	'reference/global/database': { protocol: 'JSBMbModelTool' },
+	'reference/global/note': { protocol: 'JSBMbBookNote', only: ['class'] },
+	'reference/global/self': { protocol: 'JSBJSExtension' },
+};
+
+function protocolFromTitle(title: string): string {
+	return `JSB${title.replace(/\s+/g, '')}`;
+}
+
+function selectorGuessFromDecl(decl: string): string {
+	const stripped = decl.split('//', 1)[0].trim().replace(/;$/, '').trim();
+	const noPrefix = stripped.replace(/^[-+]\s*\([^)]*\)\s*/, '').trim();
+	if (!noPrefix.includes(':')) return noPrefix.split(/\s|\(/, 1)[0].trim();
+	const parts = noPrefix.split(':');
+	const labels = parts.slice(0, -1).map((p) => {
+		const tokens = p.match(/[A-Za-z_][A-Za-z0-9_]*/g);
+		return tokens && tokens.length ? tokens[tokens.length - 1] : '';
+	});
+	return `${labels.join(':')}:`;
+}
+
+function jsNameFromObjcDecl(decl: string): string {
+	const stripped = decl.split('//', 1)[0].trim().replace(/;$/, '').trim();
+	const noPrefix = stripped.replace(/^[-+]\s*\([^)]*\)\s*/, '').trim();
+	if (!noPrefix.includes(':')) return noPrefix.split(/\s|\(/, 1)[0].trim();
+	const parts = noPrefix.split(':');
+	const labels = parts.slice(0, -1).map((p) => {
+		const tokens = p.match(/[A-Za-z_][A-Za-z0-9_]*/g);
+		return tokens && tokens.length ? tokens[tokens.length - 1] : '';
+	});
+	if (!labels.length) return '';
+	let js = labels[0];
+	for (const lab of labels.slice(1)) {
+		if (!lab) continue;
+		js += lab[0].toUpperCase() + lab.slice(1);
+	}
+	return js;
+}
+
+function parseProtocolFromHeader(headerText: string, protocolName: string): JsbApi {
+	const lines = headerText.split(/\r?\n/);
+	let inProtocol = false;
+	const properties: string[] = [];
+	const instanceMethods: string[] = [];
+	const classMethods: string[] = [];
+	const exportAliases: Record<string, string> = {};
+	let pendingExportAs: string | null = null;
+
+	for (const raw of lines) {
+		const line = raw.trim();
+		if (!line || line.startsWith('#') || line.startsWith('//')) continue;
+		const start = line.match(/^@protocol\s+(\w+)\b/);
+		if (start) {
+			inProtocol = start[1] === protocolName;
+			pendingExportAs = null;
+			continue;
+		}
+		if (!inProtocol) continue;
+		if (line === '@end') break;
+
+		if (line.startsWith('JSExportAs(')) {
+			const m = line.match(/^JSExportAs\(\s*([A-Za-z_][A-Za-z0-9_]*)\s*,/);
+			if (m) pendingExportAs = m[1];
+			continue;
+		}
+		if (line.startsWith('@property')) {
+			const m = line.match(/([A-Za-z_][A-Za-z0-9_]*)\s*;\s*(?:(?:\/\/).*)?$/);
+			if (m) properties.push(m[1]);
+			continue;
+		}
+		if (line.startsWith('- (') || line.startsWith('+ (')) {
+			const jsName = pendingExportAs || jsNameFromObjcDecl(line);
+			const selector = selectorGuessFromDecl(line);
+			if (pendingExportAs) exportAliases[jsName] = selector;
+			pendingExportAs = null;
+			if (line.startsWith('+ (')) classMethods.push(jsName);
+			else instanceMethods.push(jsName);
+			continue;
+		}
+	}
+
+	const uniq = (arr: string[]) => Array.from(new Set(arr.filter(Boolean))).sort();
+	const sortedAliases = Object.fromEntries(
+		Object.entries(exportAliases).sort(([a], [b]) => a.localeCompare(b)),
+	) as Record<string, string>;
+
+	return {
+		protocol: protocolName,
+		properties: uniq(properties),
+		instance_methods: uniq(instanceMethods),
+		class_methods: uniq(classMethods),
+		export_aliases: sortedAliases,
+	};
+}
+
+async function loadHeaderText(protocol: string): Promise<{ source: string; text: string } | null> {
+	const response = await fetch('/definitions-manifest.json');
+	if (!response.ok) throw new Error(`manifest HTTP ${response.status}`);
+	const manifest = (await response.json()) as Record<string, string>;
+	const source = manifest[protocol];
+	if (!source) return null;
+
+	const headerResponse = await fetch(`/definitions/${source}`);
+	if (!headerResponse.ok) throw new Error(`header HTTP ${headerResponse.status}`);
+	return { source, text: await headerResponse.text() };
+}
+
+function ApiList({
+	title,
+	items,
+	suffix = '',
+}: {
+	title: string;
+	items: string[];
+	suffix?: string;
+}) {
+	if (!items.length) return null;
+	return (
+		<>
+			<h3>{title}</h3>
+			<ul>
+				{items.map((item) => (
+					<li key={item}>
+						<code>
+							{item}
+							{suffix}
+						</code>
+					</li>
+				))}
+			</ul>
+		</>
+	);
+}
+
+export function JsbApiFooter({ slug, title }: { slug: string; title: string }) {
+	const config = GLOBAL_PAGE_PROTOCOL_MAP[slug];
+	const protocol = useMemo(() => config?.protocol ?? protocolFromTitle(title), [config?.protocol, title]);
+	const [state, setState] = useState<
+		| { status: 'loading' }
+		| { status: 'hidden' }
+		| { status: 'ready'; api: JsbApi; source: string }
+	>({ status: 'loading' });
+
+	useEffect(() => {
+		if (!slug.startsWith('reference/')) {
+			setState({ status: 'hidden' });
+			return;
+		}
+
+		let cancelled = false;
+		setState({ status: 'loading' });
+		loadHeaderText(protocol)
+			.then((loaded) => {
+				if (cancelled) return;
+				if (!loaded) {
+					setState({ status: 'hidden' });
+					return;
+				}
+				setState({
+					status: 'ready',
+					api: parseProtocolFromHeader(loaded.text, protocol),
+					source: loaded.source,
+				});
+			})
+			.catch((error: unknown) => {
+				console.error('Failed to load JSB API footer', {
+					protocol,
+					slug,
+					error,
+				});
+				if (!cancelled) setState({ status: 'hidden' });
+			});
+
+		return () => {
+			cancelled = true;
+		};
+	}, [protocol, slug]);
+
+	if (state.status === 'hidden') return null;
+
+	const only = new Set(config?.only ?? ['properties', 'class', 'instance', 'aliases']);
+	const aliasKeys = state.status === 'ready' ? Object.keys(state.api.export_aliases) : [];
+
+	return (
+		<section className="jsb-api" data-jsb-api>
+			<details className="jsb-api__details">
+				<summary className="jsb-api__summary">头文件API清单</summary>
+				<p className="jsb-api__meta">
+					{state.status === 'loading' ? '正在加载...' : ''}
+				</p>
+				<p className="jsb-api__meta">
+					协议：<code>{protocol}</code>，来源：
+					<code>{state.status === 'ready' ? state.source : '-'}</code>
+				</p>
+				{state.status === 'ready' ? (
+					<div>
+						{only.has('properties') ? <ApiList title="属性" items={state.api.properties} /> : null}
+						{only.has('class') ? <ApiList title="类方法" items={state.api.class_methods} suffix="()" /> : null}
+						{only.has('instance') ? (
+							<ApiList title="实例方法" items={state.api.instance_methods} suffix="()" />
+						) : null}
+						{only.has('aliases') && aliasKeys.length ? (
+							<>
+								<h3>JSExportAs别名</h3>
+								<table>
+									<thead>
+										<tr>
+											<th>JS名</th>
+											<th>ObjC selector(推断)</th>
+										</tr>
+									</thead>
+									<tbody>
+										{aliasKeys.map((jsName) => (
+											<tr key={jsName}>
+												<td>
+													<code>{jsName}</code>
+												</td>
+												<td>
+													<code>{state.api.export_aliases[jsName]}</code>
+												</td>
+											</tr>
+										))}
+									</tbody>
+								</table>
+							</>
+						) : null}
+					</div>
+				) : null}
+			</details>
+		</section>
+	);
+}