mn-docs-mcp 0.1.0

package/src/components/Search.astro

@@ -0,0 +1,330 @@
+---
+/**
+ * 覆盖 Starlight 默认 Search 组件：
+ * 默认实现只在 DOMContentLoaded 时初始化 Pagefind UI。
+ * 但 Cloudflare Rocket Loader 可能把 module script 延迟到 DOMContentLoaded 之后才执行，
+ * 导致监听器永远不触发，从而出现“搜索弹窗空白”。
+ *
+ * 这里改为：
+ * - 若页面已非 loading：立即初始化
+ * - 否则等待 DOMContentLoaded
+ * 并用全局标记避免重复初始化。
+ */
+import project from 'virtual:starlight/project-context';
+ 
+const pagefindTranslations = {
+	placeholder: Astro.locals.t('search.label'),
+	...Object.fromEntries(
+		Object.entries(Astro.locals.t.all())
+			.filter(([key]) => key.startsWith('pagefind.'))
+			.map(([key, value]) => [key.replace('pagefind.', ''), value])
+	),
+};
+ 
+const dataAttributes: DOMStringMap = { 'data-translations': JSON.stringify(pagefindTranslations) };
+if (project.trailingSlash === 'never') dataAttributes['data-strip-trailing-slash'] = '';
+---
+
+<site-search class={Astro.props.class} {...dataAttributes}>
+	<button
+		data-open-modal
+		disabled
+		aria-label={Astro.locals.t('search.label')}
+		aria-keyshortcuts="Control+K"
+	>
+		<svg aria-hidden="true" width="16" height="16" viewBox="0 0 24 24" fill="currentColor">
+			<path
+				d="M21.71 20.29 18 16.61A9 9 0 1 0 16.61 18l3.68 3.68a.999.999 0 0 0 1.42 0 1 1 0 0 0 0-1.39ZM11 18a7 7 0 1 1 0-14 7 7 0 0 1 0 14Z"
+			/>
+		</svg>
+		<span class="sl-hidden md:sl-block" aria-hidden="true">{Astro.locals.t('search.label')}</span>
+		<kbd class="sl-hidden md:sl-flex" style="display: none;">
+			<kbd>{Astro.locals.t('search.ctrlKey')}</kbd><kbd>K</kbd>
+		</kbd>
+	</button>
+
+	<dialog style="padding:0" aria-label={Astro.locals.t('search.label')}>
+		<div class="dialog-frame sl-flex">
+			{
+				/* TODO: Make the layout of this button flexible to accommodate different word lengths. Currently hard-coded for English: “Cancel” */
+			}
+			<button data-close-modal class="sl-flex md:sl-hidden">
+				{Astro.locals.t('search.cancelLabel')}
+			</button>
+			{
+				import.meta.env.DEV ? (
+					<div style="margin: auto; text-align: center; white-space: pre-line;" dir="ltr">
+						<p>{Astro.locals.t('search.devWarning')}</p>
+					</div>
+				) : (
+					<div class="search-container">
+						<div id="starlight__search" />
+					</div>
+				)
+			}
+		</div>
+	</dialog>
+</site-search>
+
+{
+	/**
+	 * This is intentionally inlined to avoid briefly showing an invalid shortcut.
+	 * Purposely using the deprecated `navigator.platform` property to detect Apple devices, as the
+	 * user agent is spoofed by some browsers when opening the devtools.
+	 */
+}
+<script is:inline>
+	(() => {
+		const openBtn = document.querySelector('button[data-open-modal]');
+		const shortcut = openBtn?.querySelector('kbd');
+		if (!openBtn || !(shortcut instanceof HTMLElement)) return;
+		const platformKey = shortcut.querySelector('kbd');
+		if (platformKey && /(Mac|iPhone|iPod|iPad)/i.test(navigator.platform)) {
+			platformKey.textContent = '⌘';
+			openBtn.setAttribute('aria-keyshortcuts', 'Meta+K');
+		}
+		shortcut.style.display = '';
+	})();
+</script>
+
+<script>
+	import { pagefindUserConfig } from 'virtual:starlight/pagefind-config';
+
+	const PAGEFIND_INIT_FLAG = '__starlight_pagefind_ui_initialized__';
+
+	class SiteSearch extends HTMLElement {
+		constructor() {
+			super();
+			const openBtn = this.querySelector<HTMLButtonElement>('button[data-open-modal]')!;
+			const closeBtn = this.querySelector<HTMLButtonElement>('button[data-close-modal]')!;
+			const dialog = this.querySelector('dialog')!;
+			const dialogFrame = this.querySelector('.dialog-frame')!;
+
+			/** Close the modal if a user clicks on a link or outside of the modal. */
+			const onClick = (event: MouseEvent) => {
+				const isLink = 'href' in (event.target || {});
+				if (
+					isLink ||
+					(document.body.contains(event.target as Node) &&
+						!dialogFrame.contains(event.target as Node))
+				) {
+					closeModal();
+				}
+			};
+
+			const openModal = (event?: MouseEvent) => {
+				dialog.showModal();
+				document.body.toggleAttribute('data-search-modal-open', true);
+				this.querySelector('input')?.focus();
+				event?.stopPropagation();
+				window.addEventListener('click', onClick);
+			};
+
+			const closeModal = () => dialog.close();
+
+			openBtn.addEventListener('click', openModal);
+			openBtn.disabled = false;
+			closeBtn.addEventListener('click', closeModal);
+
+			dialog.addEventListener('close', () => {
+				document.body.toggleAttribute('data-search-modal-open', false);
+				window.removeEventListener('click', onClick);
+			});
+
+			// Listen for `ctrl + k` and `cmd + k` keyboard shortcuts.
+			window.addEventListener('keydown', (e) => {
+				if ((e.metaKey === true || e.ctrlKey === true) && e.key === 'k') {
+					dialog.open ? closeModal() : openModal();
+					e.preventDefault();
+				}
+			});
+
+			let translations = {};
+			try {
+				translations = JSON.parse(this.dataset.translations || '{}');
+			} catch {}
+
+			const shouldStrip = this.dataset.stripTrailingSlash !== undefined;
+			const stripTrailingSlash = (path: string) => path.replace(/(.)\/(#.*)?$/, '$1$2');
+			const formatURL = shouldStrip ? stripTrailingSlash : (path: string) => path;
+
+			const initPagefind = async () => {
+				if (import.meta.env.DEV) return;
+				// 防止 Header / MobileMenu 等场景重复挂载
+				if ((window as any)[PAGEFIND_INIT_FLAG]) return;
+				(window as any)[PAGEFIND_INIT_FLAG] = true;
+
+				const onIdle = window.requestIdleCallback || ((cb) => setTimeout(cb, 1));
+				onIdle(async () => {
+					// @ts-expect-error — Missing types for @pagefind/default-ui package.
+					const { PagefindUI } = await import('@pagefind/default-ui');
+					new PagefindUI({
+						...pagefindUserConfig,
+						element: '#starlight__search',
+						baseUrl: import.meta.env.BASE_URL,
+						bundlePath: import.meta.env.BASE_URL.replace(/\/$/, '') + '/pagefind/',
+						showImages: false,
+						translations,
+						showSubResults: true,
+						processResult: (result: { url: string; sub_results: Array<{ url: string }> }) => {
+							result.url = formatURL(result.url);
+							result.sub_results = result.sub_results.map((sub_result) => {
+								sub_result.url = formatURL(sub_result.url);
+								return sub_result;
+							});
+						},
+					});
+				});
+			};
+
+			// Rocket Loader 可能让 script 在 DOMContentLoaded 之后才执行：因此不能只监听事件
+			if (document.readyState === 'loading') {
+				window.addEventListener('DOMContentLoaded', initPagefind, { once: true });
+			} else {
+				void initPagefind();
+			}
+		}
+	}
+	customElements.define('site-search', SiteSearch);
+</script>
+
+<style>
+	@layer starlight.core {
+		site-search {
+			display: contents;
+		}
+		button[data-open-modal] {
+			display: flex;
+			align-items: center;
+			gap: 0.5rem;
+			border: 0;
+			background-color: transparent;
+			color: var(--sl-color-gray-1);
+			cursor: pointer;
+			height: 2.5rem;
+			font-size: var(--sl-text-xl);
+		}
+
+		@media (min-width: 50rem) {
+			button[data-open-modal] {
+				border: 1px solid var(--sl-color-gray-5);
+				border-radius: 0.5rem;
+				padding-inline-start: 0.75rem;
+				padding-inline-end: 0.5rem;
+				background-color: var(--sl-color-black);
+				color: var(--sl-color-gray-2);
+				font-size: var(--sl-text-sm);
+				width: 100%;
+				max-width: 22rem;
+			}
+			button[data-open-modal]:hover {
+				border-color: var(--sl-color-gray-2);
+				color: var(--sl-color-white);
+			}
+
+			button[data-open-modal] > :last-child {
+				margin-inline-start: auto;
+			}
+		}
+
+		button > kbd {
+			border-radius: 0.25rem;
+			font-size: var(--sl-text-2xs);
+			gap: 0.25em;
+			padding-inline: 0.375rem;
+			background-color: var(--sl-color-gray-6);
+		}
+
+		kbd {
+			font-family: var(--__sl-font);
+		}
+
+		dialog {
+			margin: 0;
+			background-color: var(--sl-color-gray-6);
+			border: 1px solid var(--sl-color-gray-5);
+			width: 100%;
+			max-width: 100%;
+			height: 100%;
+			max-height: 100%;
+			box-shadow: var(--sl-shadow-lg);
+		}
+		dialog[open] {
+			display: flex;
+		}
+
+		dialog::backdrop {
+			background-color: var(--sl-color-backdrop-overlay);
+			-webkit-backdrop-filter: blur(0.25rem);
+			backdrop-filter: blur(0.25rem);
+		}
+
+		.dialog-frame {
+			position: relative;
+			overflow: auto;
+			flex-direction: column;
+			flex-grow: 1;
+			gap: 1rem;
+			padding: 1rem;
+		}
+
+		button[data-close-modal] {
+			position: absolute;
+			z-index: 1;
+			align-items: center;
+			align-self: flex-end;
+			height: calc(64px * var(--pagefind-ui-scale));
+			padding: 0.25rem;
+			border: 0;
+			background: transparent;
+			cursor: pointer;
+			color: var(--sl-color-text-accent);
+		}
+
+		#starlight__search {
+			--pagefind-ui-primary: var(--sl-color-text);
+			--pagefind-ui-text: var(--sl-color-gray-2);
+			--pagefind-ui-font: var(--__sl-font);
+			--pagefind-ui-background: var(--sl-color-black);
+			--pagefind-ui-border: var(--sl-color-gray-5);
+			--pagefind-ui-border-width: 1px;
+			--pagefind-ui-tag: var(--sl-color-gray-5);
+			--sl-search-cancel-space: 5rem;
+		}
+
+		:root[data-theme='light'] #starlight__search {
+			--pagefind-ui-tag: var(--sl-color-gray-6);
+		}
+
+		@media (min-width: 50rem) {
+			#starlight__search {
+				--sl-search-cancel-space: 0px;
+			}
+
+			dialog {
+				margin: 4rem auto auto;
+				border-radius: 0.5rem;
+				width: 90%;
+				max-width: 40rem;
+				height: max-content;
+				min-height: 15rem;
+				max-height: calc(100% - 8rem);
+			}
+
+			.dialog-frame {
+				padding: 1.5rem;
+			}
+		}
+	}
+</style>
+
+<style is:global>
+	@import url('@pagefind/default-ui/css/ui.css') layer(starlight.core);
+
+	@layer starlight.core {
+		[data-search-modal-open] {
+			overflow: hidden;
+		}
+	}
+</style>
+

package/src/content/docs/guides/contributing.md

@@ -0,0 +1,82 @@
+---
+title: 贡献指南
+description: 文档贡献流程与格式规范（API 参考、教程、Markdown 约定等）。
+---
+
+本仓库是 MarginNote 插件开发文档，欢迎修正错漏、补充示例、新增 API 说明等。贡献前请先开 Issue 讨论较大改动，小修正（如 typo、单页补充）可直接提 Pull Request。
+
+## 贡献流程
+
+1. **Fork** 本仓库到你的 GitHub 账号。
+2. **创建分支**：从默认分支（如 `main`）拉取新分支，建议命名 `docs/xxx` 或 `fix/typo-xxx`。
+3. **修改**：在本地或 GitHub 网页编辑器中修改文档。
+4. **提交并推送**：提交到你的 Fork，推送到 GitHub。
+5. **发起 Pull Request**：在本仓库创建 PR，目标分支为默认分支（如 `main`）。
+
+**PR 描述建议包含**：修改类型（纠错 / 新增教程 / 新增或修订 API 页）、涉及文件或路径、简要说明。
+
+## 文档结构约定
+
+- **目录**：`src/content/docs/` 下分为：
+  - `guides/`：教程与 Cookbook 配方；
+  - `reference/`：API 参考，按 `global`、`marginnote`、`foundation`、`uikit`、`quartzcore`、`utility` 等子目录组织。
+- **新增页面**：参考同类型现有页面。若为 API 参考，需符合下述「API 参考格式」；若为教程或 Cookbook，需符合「教程与指南格式」。
+- **侧栏**：若新增的是 `reference/` 下且位于已配置 `autogenerate` 的目录（如 Foundation、UIKit），侧栏会自动出现；若为 `guides/` 新页或新目录，需在 `astro.config.mjs` 的 `sidebar` 中手动添加对应 `slug`。
+
+## API 参考文档格式规范
+
+与本站已统一的风格一致，所有 API 参考页需遵守以下格式。
+
+### Frontmatter
+
+必须包含：
+
+- `title`：页面标题（如 `Application`）。
+- `description`：简短一句，用于列表与 SEO。
+
+### 方法（方法单列）
+
+- 每个方法一个三级标题：`### \`methodName\``。
+- 可选：标题下方一行简短说明。
+- **签名代码块**：使用 ` ```javascript `，内容为方法签名，例如 `static sharedInstance(): Application` 或 `count(): number`，然后 ` ``` `。
+- **Parameters**（若有参数）：
+  - 标题：`**Parameters:**`
+  - 表头：`| Name | Type | Description |`
+  - 每行一个参数，使用表格行。
+- **Return Value**：
+  - 标题：`**Return Value:**`
+  - 使用列表（如 `- 类型: 说明`）或表格给出返回值类型与简短说明。
+
+### 属性
+
+使用表格，表头：`| 属性 | 类型 | 说明 |`。只读/可写可在说明列注明。
+
+### 类成员与实例成员
+
+- 二级标题：`## 类成员 (Class members)`、`## 实例成员 (Instance members)`。
+- 可按需用三级标题分组（如「创建」「查询」），再在其下按上述方法/属性格式书写。
+
+### 相关链接
+
+页面末尾可使用 `## 相关` 列出与本页相关的其他 API 或教程链接（Markdown 链接，如 `[Application](/reference/global/application/)`）。
+
+参考示例：[Application](/reference/global/application/)。
+
+## 教程与指南页格式规范
+
+- **Frontmatter**：必须包含 `title`、`description`。
+- **正文**：用二级标题 `##` 划分大节，三级标题 `###` 划分小节；步骤用有序列表，说明用无序列表或段落。
+- **代码**：使用围栏代码块并标明语言（如 `javascript`、`json`）；若为配置文件片段，注明文件名（如「在插件根目录创建 `mnaddon.json`」）。
+- **链接**：站内链接使用以 `/` 开头的路径，如 `/guides/getting-started/`、`/reference/global/application/`。
+
+参考示例：[快速开始](/guides/getting-started/)。
+
+## 通用 Markdown 与书写约定
+
+- **语言**：文档正文与说明统一使用**简体中文**；API 名称、代码、技术术语保留英文。
+- **标点**：中文句子使用中文标点；英文或代码片段内使用英文标点。
+- **专有名词**：MarginNote、API、JavaScript 等大小写保持一致；首次出现可加简短解释。
+- **链接**：避免裸 URL，使用 `[描述](url)` 或 `[描述](/path/)`；API 交叉引用建议用「相关」小节或正文内链接到对应 reference 页。
+- **代码块**：标注语言、保持缩进一致；长示例可省略无关部分并用注释说明。
+
+若对某条规范有疑问或建议，欢迎在 Issue 中提出。

package/src/content/docs/guides/cookbook/addon-settings.md

@@ -0,0 +1,53 @@
+---
+title: 插件设置页
+description: 使用 NSUserDefaults 与简单 UI（UISwitch/UITextField）实现插件设置页。
+---
+
+**场景**：在插件面板或单独设置页中提供一个开关或输入框，保存用户选择，并在下次启动或打开笔记本时读取（例如「是否显示面板」「API Key」等）。
+
+**步骤**：
+
+1. 使用 **NSUserDefaults** 存储键值（如 `my_addon_show_panel`、`my_addon_api_key`）。
+2. 在 UI 中提供 UISwitch 或 UITextField；开关变化或确认时调用 `setBoolForKey` / `setObjectForKey`。
+3. 在需要读取的地方（如 `notebookWillOpen` 延迟后、或工具栏按钮逻辑）用 `boolForKey` / `objectForKey` 读取。
+
+**示例：一个开关「是否在打开笔记本时自动显示面板」**
+
+```javascript
+// 读取
+var showPanel = NSUserDefaults.standardUserDefaults().boolForKey("my_addon_show_panel");
+// 默认 true，仅当从未设置时为 undefined，可做默认值处理
+if (showPanel === undefined) showPanel = true;
+
+// 在设置 UI 中，用户切换 UISwitch 时：
+switchAction: function (sender) {
+  NSUserDefaults.standardUserDefaults().setBoolForKey(sender.on, "my_addon_show_panel");
+}
+```
+
+在 `notebookWillOpen` 中延迟 0.2 秒后根据 `showPanel` 决定是否 `studyController.view.addSubview(self.panelView)`（参见 [生命周期与窗口](/guides/lifecycle-and-window/)）。
+
+**示例：一个文本输入（如 API Key）**
+
+```javascript
+// 读取
+var apiKey = NSUserDefaults.standardUserDefaults().objectForKey("my_addon_api_key");
+if (apiKey) textField.text = apiKey;
+
+// 用户点击「保存」时：
+var newKey = textField.text;
+NSUserDefaults.standardUserDefaults().setObjectForKey(newKey, "my_addon_api_key");
+Application.sharedInstance().showHUD("已保存", self.window, 2);
+```
+
+若需用该 Key 发起网络请求，可参考 [调用远程 API](/guides/cookbook/network-api-call/) 和 [网络请求](/guides/network-requests/)。保存后可选择调用简单 API 验证 Key 是否有效。
+
+**完整流程简述**：
+
+1. 用 JSB.defineClass 定义设置页的 ViewController（或直接在插件实例上创建视图），包含 UISwitch、UITextField、保存按钮等。
+2. 在 viewDidLoad 或显示时从 NSUserDefaults 读取并填充控件。
+3. 在 UISwitch 的 action 或保存按钮的 action 中写回 NSUserDefaults。
+4. 插件主逻辑（如是否显示面板）在需要时从 NSUserDefaults 读取。
+5. （可选）保存 API Key 后调用简单接口验证是否有效。
+
+**相关**：[存储与文件](/guides/storage-and-files/)、[NSUserDefaults](/reference/foundation/ns-user-defaults/)、[原生 UI](/guides/native-ui/)、[调用远程 API](/guides/cookbook/network-api-call/)

package/src/content/docs/guides/cookbook/append-selection-as-comment.md

@@ -0,0 +1,46 @@
+---
+title: 将选区追加为评论
+description: 读取当前文档选区文本，追加到当前焦点笔记的评论中。
+---
+
+**场景**：用户在 PDF 中选中一段文字后点击插件按钮，将这段文字作为一条文本评论追加到当前在脑图中选中的笔记上。
+
+**步骤**：
+
+1. 获取 StudyController、当前文档控制器与焦点笔记。
+2. 读取 `currentDocumentController.selectionText` 和 `notebookController.focusNote`。
+3. 若两者均存在且选区非空，在 UndoManager.undoGrouping 中调用 `focusNote.appendTextComment(selectionText)`。
+4. 调用 `Application.refreshAfterDBChanged(topicid)` 并 showHUD 提示。
+
+**完整示例**：
+
+```javascript
+function appendSelectionAsComment() {
+  var studyController = Application.sharedInstance().studyController(self.window);
+  if (!studyController) return;
+
+  var docController = studyController.readerController.currentDocumentController;
+  var focusNote = studyController.notebookController.focusNote;
+  var text = docController ? docController.selectionText : null;
+
+  if (!focusNote) {
+    Application.sharedInstance().alert("请先在脑图中选中一条笔记");
+    return;
+  }
+  if (!text || text.length === 0) {
+    Application.sharedInstance().alert("请在文档中选中一段文字");
+    return;
+  }
+
+  var topicid = focusNote.notebookId;
+  UndoManager.sharedInstance().undoGrouping("追加选区为评论", topicid, function () {
+    focusNote.appendTextComment(text);
+  });
+  Application.sharedInstance().refreshAfterDBChanged(topicid);
+  Application.sharedInstance().showHUD("已追加为评论", self.window, 2);
+}
+```
+
+可将该函数绑定到工具栏按钮的 selector（如 `appendSelectionAsComment:`），在实例方法中调用 `appendSelectionAsComment()`。
+
+**相关**：[脑图与选区](/guides/mindmap-and-selection/)、[MbBookNote.appendTextComment](/reference/marginnote/mb-book-note/)、[UndoManager](/reference/utility/undo-manager/)

package/src/content/docs/guides/cookbook/batch-rename-notes.md

@@ -0,0 +1,53 @@
+---
+title: 批量修改笔记标题
+description: 遍历当前笔记本下的笔记，按规则修改 noteTitle，并用 undoGrouping 包裹。
+---
+
+**场景**：在当前笔记本中，对所有根笔记或其子笔记按规则批量修改标题（例如加前缀、替换关键词）。
+
+**步骤**：
+
+1. 获取当前笔记本 ID（如从 `studyController.notebookController.notebookId`）。
+2. 用 `Database.getNotebookById(topicId)` 取笔记本，得到 `notebook.notes`（根笔记数组）。
+3. 递归或遍历所有笔记，按你的规则修改 `note.noteTitle`。
+4. 将所有修改放在 **UndoManager.undoGrouping(actionName, topicid, block)** 的 block 中执行。
+5. 执行后调用 `Application.sharedInstance().refreshAfterDBChanged(topicid)`。
+
+**完整示例**：给当前笔记本下所有根笔记的标题加前缀 `"[已读] "`。
+
+```javascript
+function batchRenameAddPrefix() {
+  var studyController = Application.sharedInstance().studyController(self.window);
+  if (!studyController) return;
+  var topicid = studyController.notebookController.notebookId;
+  if (!topicid) return;
+
+  var notebook = Database.sharedInstance().getNotebookById(topicid);
+  if (!notebook || !notebook.notes || notebook.notes.length === 0) {
+    Application.sharedInstance().alert("当前笔记本没有笔记");
+    return;
+  }
+
+  var prefix = "[已读] ";
+  UndoManager.sharedInstance().undoGrouping("批量加前缀", topicid, function () {
+    function processNotes(notes) {
+      for (var i = 0; i < notes.length; i++) {
+        var note = notes[i];
+        if (note.noteTitle && note.noteTitle.indexOf(prefix) !== 0) {
+          note.noteTitle = prefix + note.noteTitle;
+        }
+        if (note.childNotes && note.childNotes.length > 0) {
+          processNotes(note.childNotes);
+        }
+      }
+    }
+    processNotes(notebook.notes);
+  });
+  Application.sharedInstance().refreshAfterDBChanged(topicid);
+  Application.sharedInstance().showHUD("已批量加前缀", self.window, 2);
+}
+```
+
+可将 `batchRenameAddPrefix` 绑定到工具栏按钮的 selector（如 `batchRename:`），在 `batchRename:` 中调用 `batchRenameAddPrefix()`。
+
+**相关**：[笔记与数据库](/guides/notes-and-database/)、[MbBookNote](/reference/marginnote/mb-book-note/)、[UndoManager](/reference/utility/undo-manager/)