chore(publish): release v2.2.5

fix: #1265

.github/DISCUSSION_TEMPLATE/note-templates.yml

@@ -43,7 +43,6 @@ body:
         - Item
         - Text
         - QuickInsert
-        - QuickBackLink
         - QuickImport
         - QuickNote
         - ExportMDFileName

.vscode/toolkit.code-snippets

@@ -18,13 +18,13 @@
       "\tremoveIfExists: ${13:true},",
       "\tcustomCheck: (doc: Document, options: ElementOptions) => ${14:true},",
       "\tchildren: [$15]",
-      "}, ${16:container});"
-    ]
+      "}, ${16:container});",
+    ],
   },
   "appendElement - minimum": {
     "scope": "javascript,typescript",
     "prefix": "appendElement",
-    "body": "appendElement({ tag: '$1' }, $2);"
+    "body": "appendElement({ tag: '$1' }, $2);",
   },
   "register Notifier": {
     "scope": "javascript,typescript",
@@ -39,7 +39,7 @@
       "\t) => {",
       "\t\t$0",
       "\t}",
-      "});"
-    ]
-  }
+      "});",
+    ],
+  },
 }

README.md

@@ -90,7 +90,7 @@ and:
 
 - Download the plugin (.xpi file) from below.
 
-  - [Latest Version: 2.2.1](https://github.com/windingwind/zotero-better-notes/releases/download/v2.2.1/better-notes-for-zotero.xpi)
+  - [Latest Version: 2.2.5](https://github.com/windingwind/zotero-better-notes/releases/download/v2.2.5/better-notes-for-zotero.xpi)
   - [Latest Stable](https://github.com/windingwind/zotero-better-notes/releases/latest)
   - [All Releases](https://github.com/windingwind/zotero-better-notes/releases)
 
@@ -240,6 +240,17 @@ BN provides APIs for other plugin developers in `Zotero.BetterNotes.api.${API_MO
 - `$export`: Export note
 - `$import`: Import note
 - `editor`: Note editor APIs. Give your script full control of contents in the note editor.
+- `note`: Note APIs. Parse and manipulate note content.
+- `relation`: Note relation APIs. Get and set note relations.
+- `utils`: Utility functions.
+
+### Concepts about Note-Related APIs
+
+In Zotero, the content of a note is stored as rich text, while when a note is opened in the note editor, it is rendered by ProseMirror as HTML.
+
+Most of the time, it is recommended to use the `editor` API to interact with the content of the note, as it supports undo/redo and other features provided by editor. The `editor` API provides a set of powerful functions to analyze and manipulate the content in the note editor. Most of them needs an `editor` instance as the input, you can get the instance by calling `Zotero.BetterNotes.api.editor.getEditorInstance(noteId)`.
+
+However, if note is not opened in the editor, you cannot get the `editor` instance. In this case, you can use the `note` API to interact with the content of the note.
 
 ## 🔧 Development
 
@@ -256,14 +267,31 @@ npm run build
 
 The plugin is built to `./builds/*.xpi`.
 
+To debug, run
+
+```bash
+npm run start
+```
+
+This will open a new Zotero instance with the plugin installed.
+
+To test the plugin, run
+
+```bash
+npm run test
+```
+
+This will run the tests in the `./test` directory.
+
 ## 🔔 Disclaimer
 
 Use this code under AGPL. No warranties are provided. Keep the laws of your locality in mind!
 
 ## 🔎 My Zotero Plugins
 
-- [Translate for Zotero](https://github.com/windingwind/zotero-pdf-translate): PDF translation for Zotero
+- [Translate for Zotero](https://github.com/windingwind/zotero-pdf-translate): Translate PDF, EPub, webpage, metadata, annotations, notes to the target language.
 - [Actions & Tags for Zotero](https://github.com/windingwind/zotero-tag): Customize your Zotero workflow.
+- [Bionic for Zotero](https://github.com/windingwind/bionic-for-zotero): Bionic reading experience with Zotero.
 
 ## 🙌 Sponsors
 

addon/chrome/content/lib/js/printUtils.js

@@ -2,7 +2,6 @@
  * License, v. 2.0. If a copy of the MPL was not distributed with this
  * file, you can obtain one at http://mozilla.org/MPL/2.0/. */
 
- var { Services } = ChromeUtils.import("resource://gre/modules/Services.jsm");
  var { XPCOMUtils } = ChromeUtils.import(
    "resource://gre/modules/XPCOMUtils.jsm"
  );

addon/chrome/content/printWrapper.xhtml

@@ -21,9 +21,6 @@
     </style>
     <script>
       var browser;
-      var { Services } = ChromeUtils.import(
-        "resource://gre/modules/Services.jsm",
-      );
       var { XPCOMUtils } = ChromeUtils.import(
         "resource://gre/modules/XPCOMUtils.jsm",
       );

addon/chrome/content/syncManager.xhtml

@@ -44,10 +44,6 @@
     </xul:keyset>
     <script>
       document.addEventListener("DOMContentLoaded", (ev) => {
-        const { Services } = ChromeUtils.import(
-          "resource://gre/modules/Services.jsm",
-        );
-
         Services.scriptloader.loadSubScript(
           "chrome://zotero/content/include.js",
           this,

addon/chrome/content/templateEditor.xhtml

@@ -45,10 +45,6 @@
     </xul:keyset>
     <script>
       document.addEventListener("DOMContentLoaded", (ev) => {
-        const { Services } = ChromeUtils.import(
-          "resource://gre/modules/Services.jsm",
-        );
-
         Services.scriptloader.loadSubScript(
           "chrome://zotero/content/include.js",
           this,

docs/about-note-template.md

@@ -13,7 +13,7 @@ One-click to import.
 ```yaml
 # This template is specifically for importing/sharing, using better
 # notes 'import from clipboard': copy the content and
-# goto Zotero menu bar, click Edit->New Template from Clipboard.
+# goto Zotero menu bar, click Tools->New Template from Clipboard.
 # Do not copy-paste this to better notes template editor directly.
 name: "[Text] Current Time"
 content: |-
@@ -32,7 +32,7 @@ content: |-
 
 </details>
 
-2. Goto Zotero menubar, click `Edit`->`New Template from Clipboard`.
+2. Goto Zotero menubar, click `Tools`->`New Template from Clipboard`.
 3. Click OK.
 
 Now you can open a note/the workspace and in editor toolbar, click `Insert Template to cursor line`. Select the template, it is inserted to the note.
@@ -88,7 +88,9 @@ Let the compiler know you are using markdown. Otherwise the template will be pro
 Allow the generated content to be updated using the `Update content from templates` in the note editor.
 The generated content will be wrapped in separators with a YAML metadata section for update.
 
-> The template with this pragma should not contain any separator (`---` or `<hr>`) in the content.
+The template with this pragma should not contain any separator (`---` or `<hr>`) in the content.
+
+> Since the first line of the content is a separator, the note generated from a template with this pragma will have a blank note title. See the solution [here](https://github.com/windingwind/zotero-better-notes/issues/1247#issuecomment-2573739339).
 
 ### `// @author`
 
@@ -148,7 +150,7 @@ If no stage pragma is given, the whole template will be processed on the default
 ```yaml
 # This template is specifically for importing/sharing, using better
 # notes 'import from clipboard': copy the content and
-# goto Zotero menu bar, click Edit->New Template from Clipboard.
+# goto Zotero menu bar, click Tools->New Template from Clipboard.
 # Do not copy-paste this to better notes template editor directly.
 name: "[Item] Example Item Template"
 content: |-
@@ -214,7 +216,6 @@ The name of builtin templates are not allowed to be modified.
 | Name                | Description                                              | Variables                             |
 | ------------------- | -------------------------------------------------------- | ------------------------------------- |
 | QuickInsert         | For forward link.                                        | link, linkText, subNoteItem, noteItem |
-| QuickBackLink       | For back link.                                           | link, linkText, subNoteItem, noteItem |
 | QuickImport         | For importing note link content.                         | link, noteItem                        |
 | QuickNote           | For generating note from annotation.                     | annotationItem, topItem, noteItem     |
 | ExportMDFileName    | For generating Markdown file name when exporting.        | noteItem                              |
@@ -408,7 +409,7 @@ A template snippet should be in YAML format (YAML has better support for multi-l
 ```yaml
 # This template is specifically for importing/sharing, using better
 # notes 'import from clipboard': copy the content and
-# goto Zotero menu bar, click Edit->New Template from Clipboard.
+# goto Zotero menu bar, click Tools->New Template from Clipboard.
 # Do not copy-paste this to better notes template editor directly.
 name: "[TYPE] TEMPLATE NAME"
 content: |-

package.json

@@ -1,6 +1,6 @@
 {
   "name": "zotero-better-notes",
-  "version": "2.2.1",
+  "version": "2.2.5",
   "description": "Everything about note management. All in Zotero.",
   "config": {
     "addonName": "Better Notes for Zotero",
@@ -18,6 +18,7 @@
     "release": "zotero-plugin release",
     "lint": "prettier --write . && eslint . --ext .ts --fix",
     "test": "zotero-plugin test  --abort-on-fail --exit-on-finish",
+    "test-dev": "zotero-plugin test  --abort-on-fail",
     "update-deps": "npm update --save"
   },
   "repository": {
@@ -32,7 +33,7 @@
   "homepage": "https://github.com/windingwind/zotero-better-notes#readme",
   "dependencies": {
     "asciidoctor": "^3.0.4",
-    "dexie": "^4.0.10",
+    "dexie": "^4.0.11",
     "diff": "^5.2.0",
     "hast-util-to-html": "^9.0.4",
     "hast-util-to-mdast": "^8.4.1",
@@ -40,7 +41,7 @@
     "hastscript": "^8.0.0",
     "html-docx-js": "^0.3.1",
     "html-docx-js-typescript": "^0.1.5",
-    "katex": "^0.16.19",
+    "katex": "^0.16.21",
     "path-browserify": "^1.0.1",
     "rehype-format": "^4.0.1",
     "rehype-parse": "^8.0.5",
@@ -57,7 +58,7 @@
     "unist-util-visit": "^5.0.0",
     "unist-util-visit-parents": "^6.0.1",
     "yamljs": "^0.3.0",
-    "zotero-plugin-toolkit": "^4.1.0"
+    "zotero-plugin-toolkit": "^4.1.1"
   },
   "devDependencies": {
     "@esbuild-plugins/node-globals-polyfill": "^0.2.3",
@@ -68,7 +69,7 @@
     "@types/html-docx-js": "^0.3.4",
     "@types/katex": "^0.16.7",
     "@types/mocha": "^10.0.10",
-    "@types/node": "^20.17.10",
+    "@types/node": "^20.17.14",
     "@types/path-browserify": "^1.0.3",
     "@types/seedrandom": "^3.0.8",
     "@types/yamljs": "^0.2.34",
@@ -85,10 +86,10 @@
     "prosemirror-transform": "^1.10.2",
     "prosemirror-view": "^1.37.1",
     "replace-in-file": "^7.2.0",
-    "typescript": "^5.7.2",
+    "typescript": "^5.7.3",
     "xslt3": "^2.7.0",
-    "zotero-plugin-scaffold": "0.2.0-beta.5",
-    "zotero-types": "^3.1.0"
+    "zotero-plugin-scaffold": "^0.2.0-beta.20",
+    "zotero-types": "^3.1.6"
   },
   "eslintConfig": {
     "env": {

src/addon.ts

@@ -66,7 +66,7 @@ class Addon {
         templates: string[];
       };
       picker: {
-        mode: "insert" | "create" | "export";
+        mode: "insert" | "create" | "export" | "pick";
         data: Record<string, any>;
       };
     };

src/extras/editor/editorStrings.ts

@@ -40,6 +40,10 @@ const editorStrings = {
     "en-US": "Copy Line Link",
     "zh-CN": "复制行链接",
   },
+  refreshTemplates: {
+    "en-US": "Update content from templates",
+    "zh-CN": "更新模板生成内容",
+  },
   heading1: {
     "en-US": "Heading 1",
     "zh-CN": "一级标题",

src/extras/editor/linkPreview.ts

@@ -144,7 +144,7 @@ class PluginState {
     height: auto;
   }
   .link-preview .primary-editor li {
-    white-space: nowrap;
+    white-space: normal;
   }
 </style>`),
     ]);

src/extras/templatePicker.ts

@@ -11,7 +11,8 @@ let args = window.arguments[0] as any;
 if (!args._initPromise) {
   args = args.wrappedJSObject;
 }
-const templateData = args.templates;
+const templateData = (args.templates as string[]) || [];
+templateData.sort();
 const multiSelect = args.multiSelect;
 let tableHelper: VirtualizedTableHelper;
 

src/hooks.ts

@@ -141,6 +141,13 @@ async function onNotify(
   if (extraData?.skipBN) {
     return;
   }
+  if (
+    ["add", "close"].includes(event) &&
+    type === "tab" &&
+    extraData[ids[0]]?.type === "note"
+  ) {
+    Zotero.Session.debounceSave();
+  }
   if (event === "select" && type === "tab") {
     onTabSelect(extraData[ids[0]].type);
   }

src/modules/annotationNote.ts

@@ -12,48 +12,101 @@ function registerReaderAnnotationButton() {
     (event) => {
       const { doc, append, params, reader } = event;
       const annotationData = params.annotation;
-      append(
-        ztoolkit.UI.createElement(doc, "div", {
-          tag: "div",
-          classList: ["icon"],
-          properties: {
-            innerHTML: ICONS.readerQuickNote,
+      const button = ztoolkit.UI.createElement(doc, "div", {
+        classList: ["icon"],
+        properties: {
+          innerHTML: getAnnotationNoteButtonInnerHTML(false),
+          title: getAnnotationNoteButtonTitle(false),
+        },
+        listeners: [
+          {
+            type: "click",
+            listener: (e) => {
+              const button = e.currentTarget as HTMLElement;
+              createNoteFromAnnotation(
+                reader._item.libraryID,
+                annotationData.id,
+                (e as MouseEvent).shiftKey ? "window" : "builtin",
+              );
+              button.innerHTML = getAnnotationNoteButtonInnerHTML(true);
+              e.preventDefault();
+            },
           },
-          listeners: [
-            {
-              type: "click",
-              listener: (e) => {
-                createNoteFromAnnotation(
-                  reader._item.libraryID,
-                  annotationData.id,
-                  (e as MouseEvent).shiftKey ? "window" : "builtin",
-                );
-                e.preventDefault();
-              },
-            },
-            {
-              type: "mouseover",
-              listener: (e) => {
-                (e.target as HTMLElement).style.backgroundColor = "#F0F0F0";
-              },
-            },
-            {
-              type: "mouseout",
-              listener: (e) => {
-                (e.target as HTMLElement).style.removeProperty(
-                  "background-color",
-                );
-              },
-            },
-          ],
-          enableElementRecord: false,
-        }),
+        ],
+        enableElementRecord: false,
+      });
+      updateAnnotationNoteButton(
+        button,
+        reader._item.libraryID,
+        annotationData.id,
       );
+      append(button);
     },
     config.addonID,
   );
 }
 
+function getAnnotationNoteButtonInnerHTML(hasNote: boolean) {
+  return `${hasNote ? ICONS.openInNewWindow : ICONS.readerQuickNote}
+<style>
+  .icon {
+    border-radius: 4px;
+    color: #ffd400;
+  }
+  .icon:hover {
+    background-color: var(--fill-quinary);
+    outline: 2px solid var(--fill-quinary);
+  }
+  .icon:active {
+    background-color: var(--fill-quarternary);
+  }
+</style>
+  `;
+}
+
+function getAnnotationNoteButtonTitle(hasNote: boolean) {
+  return hasNote ? "Open note" : "Create note from annotation";
+}
+
+function updateAnnotationNoteButton(
+  button: HTMLElement,
+  libraryID: number,
+  itemKey: string,
+) {
+  hasNoteFromAnnotation(libraryID, itemKey).then((hasNote) => {
+    button.innerHTML = getAnnotationNoteButtonInnerHTML(hasNote);
+    button.title = getAnnotationNoteButtonTitle(hasNote);
+  });
+}
+
+async function hasNoteFromAnnotation(
+  libraryID: number,
+  itemKey: string,
+): Promise<boolean> {
+  const annotationItem = Zotero.Items.getByLibraryAndKey(
+    libraryID,
+    itemKey,
+  ) as Zotero.Item;
+  if (!annotationItem) {
+    return false;
+  }
+
+  const linkTarget = await addon.api.relation.getLinkTargetByAnnotation(
+    annotationItem.libraryID,
+    annotationItem.key,
+  );
+  if (linkTarget) {
+    const targetItem = Zotero.Items.getByLibraryAndKey(
+      linkTarget.toLibID,
+      linkTarget.toKey,
+    );
+    if (targetItem) {
+      return true;
+    }
+  }
+  return false;
+}
+
 async function createNoteFromAnnotation(
   libraryID: number,
   itemKey: string,

src/modules/template/controller.ts

@@ -62,7 +62,12 @@ function removeTemplate(keyName: string | undefined): void {
   addon.data.template.data?.deleteKey(keyName);
 }
 
-function importTemplateFromClipboard(text?: string) {
+function importTemplateFromClipboard(
+  text?: string,
+  options: {
+    quiet?: boolean;
+  } = {},
+) {
   if (!text) {
     text = Zotero.Utilities.Internal.getClipboard("text/plain") || "";
   }
@@ -83,7 +88,10 @@ function importTemplateFromClipboard(text?: string) {
     showHint("The copied template is invalid");
     return;
   }
-  if (!window.confirm(`Import template "${template.name}"?`)) {
+  if (
+    !options.quiet &&
+    !window.confirm(`Import template "${template.name}"?`)
+  ) {
     return;
   }
   setTemplate({ name: template.name, text: template.content });
@@ -91,4 +99,5 @@ function importTemplateFromClipboard(text?: string) {
   if (addon.data.template.editor.window) {
     addon.data.template.editor.window.refresh();
   }
+  return template.name;
 }

src/modules/template/editorWindow.ts

@@ -199,8 +199,9 @@ export async function showTemplateEditor() {
     const editorWin = (_window.document.querySelector("#editor") as any)
       .contentWindow;
     await waitUtilAsync(() => editorWin?.loadMonaco);
-    const isDark = editorWin?.matchMedia("(prefers-color-scheme: dark)")
-      .matches;
+    const isDark = editorWin?.matchMedia(
+      "(prefers-color-scheme: dark)",
+    ).matches;
     const { monaco, editor } = await editorWin.loadMonaco({
       language: "javascript",
       theme: "vs-" + (isDark ? "dark" : "light"),

src/modules/template/picker.ts

@@ -20,14 +20,19 @@ async function showTemplatePicker(
   mode: "export",
   data?: Record<string, never>,
 ): Promise<void>;
-async function showTemplatePicker(): Promise<void>;
+async function showTemplatePicker(mode: "pick"): Promise<string[]>;
+async function showTemplatePicker(): Promise<any>;
 async function showTemplatePicker(
   mode: typeof addon.data.template.picker.mode = "insert",
   data: Record<string, any> = {},
-) {
+): Promise<unknown> {
   addon.data.template.picker.mode = mode;
   addon.data.template.picker.data = data;
   const selected = await openTemplatePicker();
+  // For pick mode, return selected templates
+  if (mode === "pick") {
+    return selected;
+  }
   if (!selected.length) {
     return;
   }
@@ -68,11 +73,12 @@ async function insertTemplateCallback(name: string) {
       targetNoteId: targetNoteItem.id,
     });
   }
-  await addLineToNote(
-    targetNoteItem,
-    html,
-    addon.data.template.picker.data.lineIndex,
-  );
+  let lineIndex = addon.data.template.picker.data.lineIndex;
+  // Insert to the end of the line
+  if (lineIndex >= 0) {
+    lineIndex += 1;
+  }
+  await addLineToNote(targetNoteItem, html, lineIndex);
 }
 
 async function createTemplateNoteCallback(name: string) {

src/modules/template/preview.ts

@@ -93,25 +93,6 @@ async function renderTemplatePreview(
           },
         );
       }
-    } else if (templateName.includes("QuickBackLink")) {
-      // link, linkText, subNoteItem, noteItem
-      const data = inputItems?.find((item) => item.isNote());
-      if (!data) {
-        html = messages.noNoteItem;
-      } else {
-        const link = getNoteLink(data);
-        const noteItem = new Zotero.Item("note");
-        const linkText = noteItem.getNoteTitle().trim() || "Workspace Note";
-        const subNoteItem = data;
-        html = await addon.api.template.runTemplate(
-          templateName,
-          "link, linkText, subNoteItem, noteItem",
-          [link, linkText, subNoteItem, noteItem],
-          {
-            dryRun: true,
-          },
-        );
-      }
     } else if (templateName.includes("QuickImport")) {
       // link, noteItem
       const data = inputItems?.find((item) => item.isNote());

src/modules/workspace/tab.ts

@@ -70,6 +70,7 @@ export async function restoreNoteTabs() {
       select: !!tab.selected,
     });
   }
+  Zotero.Session.debounceSave();
 }
 
 export function onUpdateNoteTabsTitle(noteItems: Zotero.Item[]) {

src/utils/convert.ts

@@ -428,11 +428,12 @@ async function rehype2remark(rehype: HRoot) {
             return mNode;
           }
           const children: any[] = [];
+          const paragraphNodes = ["list", "code", "math", "table"];
           // Merge none-list nodes inside li into the previous paragraph node to avoid line break
           while (mNode.children.length > 0) {
             const current = mNode.children.shift();
             const cached = children[children.length - 1];
-            if (current?.type !== "list") {
+            if (current?.type && !paragraphNodes.includes(current?.type)) {
               if (cached?.type === "paragraph") {
                 cached.children.push(current);
               } else {

src/utils/editor.ts

@@ -247,6 +247,13 @@ function getPositionAtLine(
   type: "start" | "end" = "end",
 ): number {
   const core = getEditorCore(editor);
+  const lineCount = getLineCount(editor);
+  if (lineIndex < 0) {
+    return 0;
+  }
+  if (lineIndex >= lineCount) {
+    return core.view.state.doc.content.size;
+  }
   const lineNodeDesc =
     core.view.docView.children[
       Math.max(0, Math.min(core.view.docView.children.length - 1, lineIndex))

src/utils/note.ts

@@ -77,7 +77,8 @@ async function addLineToNote(
     return;
   }
   const noteLines = await getLinesInNote(note);
-  if (lineIndex < 0 || lineIndex >= noteLines.length) {
+  // No need to handle the case when lineIndex is out of range, as it will always be inserted at the very end
+  if (lineIndex < 0) {
     lineIndex = noteLines.length;
   }
   ztoolkit.log(`insert to ${lineIndex}, it used to be ${noteLines[lineIndex]}`);
@@ -86,7 +87,12 @@ async function addLineToNote(
   const editor = getEditorInstance(note.id);
   if (editor && !forceMetadata) {
     // The note is opened. Add line via note editor
-    const pos = getPositionAtLine(editor, lineIndex, "start");
+    // If the lineIndex is out of range, the line will be inserted at the end (after the last line)
+    const pos = getPositionAtLine(
+      editor,
+      lineIndex,
+      lineIndex >= noteLines.length ? "end" : "start",
+    );
     ztoolkit.log("Add note line via note editor", pos);
     insert(editor, html, pos);
     // The selection is automatically moved to the next line
@@ -384,9 +390,8 @@ async function copyEmbeddedImagesInHTML(
         if (!copiedAttachment) {
           continue;
         }
-        nodes.forEach(
-          (node) =>
-            node?.setAttribute("data-attachment-key", copiedAttachment!.key),
+        nodes.forEach((node) =>
+          node?.setAttribute("data-attachment-key", copiedAttachment!.key),
         );
       }
     }

src/utils/prefs.ts

@@ -1,18 +1,38 @@
 import { config } from "../../package.json";
 
-export function getPref(key: string) {
-  return Zotero.Prefs.get(`${config.prefsPrefix}.${key}`, true);
+export {
+  getPref,
+  setPref,
+  clearPref,
+  getPrefJSON,
+  registerPrefObserver,
+  unregisterPrefObserver,
+};
+
+type _PluginPrefsMap = _ZoteroTypes.Prefs["PluginPrefsMap"];
+
+function getPref<K extends keyof _PluginPrefsMap>(key: K): _PluginPrefsMap[K];
+function getPref(key: string): string | number | boolean;
+function getPref(key: string): string | number | boolean {
+  return Zotero.Prefs.get(`${config.prefsPrefix}.${key}`, true) as any;
 }
 
-export function setPref(key: string, value: string | number | boolean) {
+function setPref<K extends keyof _PluginPrefsMap>(
+  key: K,
+  value: _PluginPrefsMap[K],
+): void;
+function setPref(key: string, value: string | number | boolean): void;
+function setPref(key: string, value: string | number | boolean) {
   return Zotero.Prefs.set(`${config.prefsPrefix}.${key}`, value, true);
 }
 
-export function clearPref(key: string) {
+function clearPref<K extends keyof _PluginPrefsMap>(key: K): void;
+function clearPref(key: string): void;
+function clearPref(key: string) {
   return Zotero.Prefs.clear(`${config.prefsPrefix}.${key}`, true);
 }
 
-export function getPrefJSON(key: string) {
+function getPrefJSON(key: string) {
   try {
     return JSON.parse(String(getPref(key) || "{}"));
   } catch (e) {
@@ -21,10 +41,15 @@ export function getPrefJSON(key: string) {
   return {};
 }
 
-export function registerPrefObserver(
+function registerPrefObserver<K extends keyof _PluginPrefsMap>(
+  key: K,
+  callback: (value: _PluginPrefsMap[K]) => void,
+): symbol;
+function registerPrefObserver(
   key: string,
   callback: (value: any) => void,
-) {
+): symbol;
+function registerPrefObserver(key: string, callback: (value: any) => void) {
   return Zotero.Prefs.registerObserver(
     `${config.prefsPrefix}.${key}`,
     callback,
@@ -32,6 +57,6 @@ export function registerPrefObserver(
   );
 }
 
-export function unregisterPrefObserver(observerID: symbol) {
+function unregisterPrefObserver(observerID: symbol) {
   return Zotero.Prefs.unregisterObserver(observerID);
 }

test/tests/export.spec.ts

@@ -0,0 +1,255 @@
+/* eslint-disable no-irregular-whitespace */
+/* eslint-disable no-useless-escape */
+import { ClipboardHelper } from "zotero-plugin-toolkit";
+import { getAddon } from "../utils/global";
+import { resetAll } from "../utils/status";
+import { getNoteContent, parseTemplateString } from "../utils/note";
+import { getTempDirectory } from "../utils/io";
+
+describe("Export", function () {
+  const addon = getAddon();
+  this.beforeAll(async function () {
+    await resetAll();
+  });
+
+  this.afterEach(async function () {});
+
+  it("api.$export.saveMD", async function () {
+    const note = new Zotero.Item("note");
+    note.setNote(getNoteContent());
+    await note.saveTx();
+
+    const tempDir = await getTempDirectory();
+
+    const filePath = PathUtils.join(tempDir, "test.md");
+
+    await getAddon().api.$export.saveMD(filePath, note.id, {
+      keepNoteLink: true,
+      withYAMLHeader: false,
+    });
+
+    debug("Note saved to", filePath);
+
+    const content = await Zotero.File.getContentsAsync(filePath);
+
+    const expected = `# Markdown Test Document
+
+## Headers
+
+# H1 Header
+
+## H2 Header
+
+### H3 Header
+
+#### H4 Header
+
+##### H5 Header
+
+###### H6 Header
+
+## Emphasis
+
+*This text is italicized.* *This text is also italicized.*
+
+**This text is bold.** **This text is also bold.**
+
+***This text is bold and italicized.*** ***This text is also bold and italicized.***
+
+## Links
+
+[Link with title](https://example.com "Title") [Link without title](https://example.com)
+
+## Images
+
+## Blockquotes
+
+> This is a blockquote.
+>
+> > Nested blockquote.
+>
+> Back to the outer blockquote.
+
+## Lists
+
+### Unordered List
+
+*   Item 1
+
+    *   Subitem 1.1
+
+        *   Subitem 1.1.1
+
+*   Item 2
+
+### Ordered List
+
+1.  First item
+
+    1.  Subitem 1.1
+
+        1.  Subitem 1.1.1
+
+2.  Second item
+
+## Code
+
+### Inline Code
+
+Here is some \`inline code\`.
+
+### Code Block
+
+\`\`\`
+def hello_world():
+    print("Hello, world!")
+
+\`\`\`
+
+## Horizontal Rules
+
+***
+
+This is text between horizontal rules
+
+***
+
+## Tables
+
+| Header 1 | Header 2 | Header 3 |
+| -------- | -------- | -------- |
+| Row 1    | Data 1.2 | Data 1.3 |
+| Row 2    | Data 2.2 | Data 2.3 |
+
+## Math
+
+### Inline Math
+
+This is an inline math equation: \$E = mc^2\$.
+
+### Block Math
+
+Below is a block math equation:
+
+\$\$
+\\\\int_a^b f(x) \\\\, dx = F(b) - F(a)
+\$\$
+
+### Complex Math
+
+Solve the quadratic equation:
+
+\$\$
+x = \\\\frac\{-b \\\\pm \\\\sqrt\{b^2 - 4ac\}\}\{2a\}
+\$\$
+
+## Nested Elements
+
+### Nested Code and Lists
+
+1.  Ordered list item
+
+    *   Unordered subitem
+
+        \`\`\`
+        console.log("Nested code block");
+
+        \`\`\`
+
+2.  This is a nested math
+
+    \$\$
+    y=x^2
+    \$\$
+
+3.  This is a inline math\$123\$
+
+4.  This is a line table
+
+    |   |   |   |
+    | - | - | - |
+    | 1 | 2 | 3 |
+    | 4 | 5 | 6 |
+    | 7 | 8 | 9 |
+
+## Special Characters
+
+Escape sequences for special characters: \\* \\_ \\\\\\\` \\[ ] ( ) # + - .
+
+## HTML in Markdown
+
+This is a HTML block inside Markdown.
+
+## Highlight Text
+
+Highlight <span style="background-color: rgba(255, 102, 102, 0.5)">text</span> is here
+
+## Colored Text
+
+Colored <span style="color: rgb(255, 32, 32)">text</span> is here
+
+## Task Lists
+
+*   Completed item
+*   Incomplete item
+
+## Strikethrough
+
+~~This text is strikethrough.~~
+
+## Recursive Elements
+
+### Recursive Links and Emphasis
+
+**[Bold link](https://example.com)**
+
+### Recursive Emphasis
+
+***Bold and nested italic within bold.***
+
+## Image
+
+IMAGE\\_PLACEHOLDER
+
+## Citation
+
+CITATION\\_PLACEHOLDER
+
+## Edge Cases
+
+### Empty Link
+
+[Link](https://)
+
+### Zotero Link
+
+[Zotero Link](zotero://note/u/123456)
+
+### Lone Asterisk
+
+*   This should not be italic.
+
+### Broken Lists
+
+*   Item 1
+
+    *   Item 2Continuation of item 2 without proper indentation.
+
+### Long Text Wrapping
+
+This is a very long paragraph that does not have any line breaks and is intended to test how the Markdown engine handles text wrapping when there are no explicit line breaks within the text.
+
+***
+
+## Conclusion
+
+This document contains a wide range of Markdown elements, including headers, lists, blockquotes, inline and block code, tables, images, links, math, and special characters. It also tests recursive and edge cases to ensure the Markdown engine is robust.
+`;
+
+    // new ClipboardHelper()
+    //   .addText(parseTemplateString(content as string))
+    //   .copy();
+
+    assert.equal(content, expected);
+  });
+});

test/tests/startup.spec.ts

@@ -1,7 +1,7 @@
-import { config } from "../../package.json";
+import { getAddon } from "../utils/global";
 
 describe("Startup", function () {
   it("should have plugin instance defined", function () {
-    assert.isNotEmpty(Zotero[config.addonRef]);
+    assert.isNotEmpty(getAddon());
   });
 });

test/tests/template.spec.ts

@@ -0,0 +1,389 @@
+/* eslint-disable no-useless-escape */
+/* eslint-disable no-irregular-whitespace */
+import { ClipboardHelper } from "zotero-plugin-toolkit";
+import { getAddon } from "../utils/global";
+import { resetAll } from "../utils/status";
+import { getNoteContent, parseTemplateString } from "../utils/note";
+
+describe("Template", function () {
+  const addon = getAddon();
+  this.beforeAll(async function () {
+    await resetAll();
+  });
+
+  this.afterEach(async function () {});
+
+  it("hooks.onImportTemplateFromClipboard", async function () {
+    const key = importTemplate();
+    assert.isNotEmpty(key);
+    addon.api.template.removeTemplate(key);
+  });
+
+  it("api.template.getTemplateText", async function () {
+    const key = importTemplate();
+    assert.isNotEmpty(addon.api.template.getTemplateText(key!));
+    addon.api.template.removeTemplate(key);
+  });
+
+  it("api.template.getTemplateText", async function () {
+    const key = importTemplate();
+    assert.isTrue(addon.api.template.getTemplateKeys().includes(key!));
+    addon.api.template.removeTemplate(key);
+  });
+
+  it("api.template.removeTemplate", async function () {
+    const key = importTemplate();
+    assert.isNotEmpty(key);
+    addon.api.template.removeTemplate(key!);
+    assert.isFalse(addon.api.template.getTemplateKeys().includes(key!));
+  });
+
+  it("api.template.renderTemplatePreview", async function () {
+    const key = importTemplate();
+    const preview = await addon.api.template.renderTemplatePreview(key!);
+    const expected = `<div data-schema-version="9"><h1>Markdown Test Document</h1>
+<h2>Headers</h2>
+<h1>H1 Header</h1>
+<h2>H2 Header</h2>
+<h3>H3 Header</h3>
+<h4>H4 Header</h4>
+<h5>H5 Header</h5>
+<h6>H6 Header</h6>
+<h2>Emphasis</h2>
+<p><em>This text is italicized.</em> <em>This text is also italicized.</em></p>
+<p><strong>This text is bold.</strong> <strong>This text is also bold.</strong></p>
+<p><strong><em>This text is bold and italicized.</em></strong> <strong><em>This text is also bold and italicized.</em></strong></p>
+<h2>Links</h2>
+<p><a href="https://example.com" title="Title" rel="noopener noreferrer nofollow">Link with title</a> <a href="https://example.com" rel="noopener noreferrer nofollow">Link without title</a></p>
+<h2>Images</h2>
+<p></p>
+<h2>Blockquotes</h2>
+<blockquote>
+<p>This is a blockquote.</p>
+<blockquote>
+<p>Nested blockquote.</p>
+</blockquote>
+<p>Back to the outer blockquote.</p>
+</blockquote>
+<h2>Lists</h2>
+<h3>Unordered List</h3>
+<ul>
+<li>
+<p>Item 1</p>
+<ul>
+<li>
+<p>Subitem 1.1</p>
+<ul>
+<li>
+Subitem 1.1.1
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li>
+Item 2
+</li>
+</ul>
+<h3>Ordered List</h3>
+<ol>
+<li>
+<p>First item</p>
+<ol>
+<li>
+<p>Subitem 1.1</p>
+<ol>
+<li>
+Subitem 1.1.1
+</li>
+</ol>
+</li>
+</ol>
+</li>
+<li>
+Second item
+</li>
+</ol>
+<h2>Code</h2>
+<h3>Inline Code</h3>
+<p>Here is some <code>inline code</code>.</p>
+<h3>Code Block</h3>
+<pre>def hello_world():
+ &nbsp; &nbsp;print("Hello, world!")
+</pre>
+<h2>Horizontal Rules</h2>
+<hr>
+<p>This is text between horizontal rules</p>
+<hr>
+<h2>Tables</h2>
+<table>
+<tbody>
+<tr>
+<th>
+<p>Header 1</p>
+</th>
+<th>
+<p>Header 2</p>
+</th>
+<th>
+<p>Header 3</p>
+</th>
+</tr>
+<tr>
+<td>
+<p>Row 1</p>
+</td>
+<td>
+<p>Data 1.2</p>
+</td>
+<td>
+<p>Data 1.3</p>
+</td>
+</tr>
+<tr>
+<td>
+<p>Row 2</p>
+</td>
+<td>
+<p>Data 2.2</p>
+</td>
+<td>
+<p>Data 2.3</p>
+</td>
+</tr>
+</tbody>
+</table>
+<h2>Math</h2>
+<h3>Inline Math</h3>
+<p>This is an inline math equation: <span class="math"><span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mi>E</mi><mo>=</mo><mi>m</mi><msup><mi>c</mi><mn>2</mn></msup></mrow><annotation encoding="application/x-tex">E = mc^2</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.6833em;"></span><span class="mord mathnormal" style="margin-right:0.05764em;">E</span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">=</span><span class="mspace" style="margin-right:0.2778em;"></span></span><span class="base"><span class="strut" style="height:0.8141em;"></span><span class="mord mathnormal">m</span><span class="mord"><span class="mord mathnormal">c</span><span class="msupsub"><span class="vlist-t"><span class="vlist-r"><span class="vlist" style="height:0.8141em;"><span style="top:-3.063em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"></span><span class="sizing reset-size6 size3 mtight"><span class="mord mtight">2</span></span></span></span></span></span></span></span></span></span></span></span>.</p>
+<h3>Block Math</h3>
+<p>Below is a block math equation:</p>
+<pre class="math"><span class="katex-display"><span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><msubsup><mo>∫</mo><mi>a</mi><mi>b</mi></msubsup><mi>f</mi><mo stretchy="false">(</mo><mi>x</mi><mo stretchy="false">)</mo><mtext> </mtext><mi>d</mi><mi>x</mi><mo>=</mo><mi>F</mi><mo stretchy="false">(</mo><mi>b</mi><mo stretchy="false">)</mo><mo>−</mo><mi>F</mi><mo stretchy="false">(</mo><mi>a</mi><mo stretchy="false">)</mo></mrow><annotation encoding="application/x-tex">\\int_a^b f(x) \\, dx = F(b) - F(a)</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:2.511em;vertical-align:-0.9119em;"></span><span class="mop"><span class="mop op-symbol large-op" style="margin-right:0.44445em;position:relative;top:-0.0011em;">∫</span><span class="msupsub"><span class="vlist-t vlist-t2"><span class="vlist-r"><span class="vlist" style="height:1.599em;"><span style="top:-1.7881em;margin-left:-0.4445em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"></span><span class="sizing reset-size6 size3 mtight"><span class="mord mathnormal mtight">a</span></span></span><span style="top:-3.8129em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"></span><span class="sizing reset-size6 size3 mtight"><span class="mord mathnormal mtight">b</span></span></span></span><span class="vlist-s">​</span></span><span class="vlist-r"><span class="vlist" style="height:0.9119em;"><span></span></span></span></span></span></span><span class="mspace" style="margin-right:0.1667em;"></span><span class="mord mathnormal" style="margin-right:0.10764em;">f</span><span class="mopen">(</span><span class="mord mathnormal">x</span><span class="mclose">)</span><span class="mspace" style="margin-right:0.1667em;"></span><span class="mord mathnormal">d</span><span class="mord mathnormal">x</span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">=</span><span class="mspace" style="margin-right:0.2778em;"></span></span><span class="base"><span class="strut" style="height:1em;vertical-align:-0.25em;"></span><span class="mord mathnormal" style="margin-right:0.13889em;">F</span><span class="mopen">(</span><span class="mord mathnormal">b</span><span class="mclose">)</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span></span><span class="base"><span class="strut" style="height:1em;vertical-align:-0.25em;"></span><span class="mord mathnormal" style="margin-right:0.13889em;">F</span><span class="mopen">(</span><span class="mord mathnormal">a</span><span class="mclose">)</span></span></span></span></span></pre>
+<h3>Complex Math</h3>
+<p>Solve the quadratic equation:</p>
+<pre class="math"><span class="katex-display"><span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mi>x</mi><mo>=</mo><mfrac><mrow><mo>−</mo><mi>b</mi><mo>±</mo><msqrt><mrow><msup><mi>b</mi><mn>2</mn></msup><mo>−</mo><mn>4</mn><mi>a</mi><mi>c</mi></mrow></msqrt></mrow><mrow><mn>2</mn><mi>a</mi></mrow></mfrac></mrow><annotation encoding="application/x-tex">x = \\frac\{-b \\pm \\sqrt\{b^2 - 4ac\}\}\{2a\}</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.4306em;"></span><span class="mord mathnormal">x</span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">=</span><span class="mspace" style="margin-right:0.2778em;"></span></span><span class="base"><span class="strut" style="height:2.2764em;vertical-align:-0.686em;"></span><span class="mord"><span class="mopen nulldelimiter"></span><span class="mfrac"><span class="vlist-t vlist-t2"><span class="vlist-r"><span class="vlist" style="height:1.5904em;"><span style="top:-2.314em;"><span class="pstrut" style="height:3em;"></span><span class="mord"><span class="mord">2</span><span class="mord mathnormal">a</span></span></span><span style="top:-3.23em;"><span class="pstrut" style="height:3em;"></span><span class="frac-line" style="border-bottom-width:0.04em;"></span></span><span style="top:-3.677em;"><span class="pstrut" style="height:3em;"></span><span class="mord"><span class="mord">−</span><span class="mord mathnormal">b</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mbin">±</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mord sqrt"><span class="vlist-t vlist-t2"><span class="vlist-r"><span class="vlist" style="height:0.9134em;"><span class="svg-align" style="top:-3em;"><span class="pstrut" style="height:3em;"></span><span class="mord" style="padding-left:0.833em;"><span class="mord"><span class="mord mathnormal">b</span><span class="msupsub"><span class="vlist-t"><span class="vlist-r"><span class="vlist" style="height:0.7401em;"><span style="top:-2.989em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"></span><span class="sizing reset-size6 size3 mtight"><span class="mord mtight">2</span></span></span></span></span></span></span></span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mbin">−</span><span class="mspace" style="margin-right:0.2222em;"></span><span class="mord">4</span><span class="mord mathnormal">a</span><span class="mord mathnormal">c</span></span></span><span style="top:-2.8734em;"><span class="pstrut" style="height:3em;"></span><span class="hide-tail" style="min-width:0.853em;height:1.08em;"><svg xmlns="http://www.w3.org/2000/svg" width="400em" height="1.08em" viewBox="0 0 400000 1080" preserveAspectRatio="xMinYMin slice"><path d="M95,702
+c-2.7,0,-7.17,-2.7,-13.5,-8c-5.8,-5.3,-9.5,-10,-9.5,-14
+c0,-2,0.3,-3.3,1,-4c1.3,-2.7,23.83,-20.7,67.5,-54
+c44.2,-33.3,65.8,-50.3,66.5,-51c1.3,-1.3,3,-2,5,-2c4.7,0,8.7,3.3,12,10
+s173,378,173,378c0.7,0,35.3,-71,104,-213c68.7,-142,137.5,-285,206.5,-429
+c69,-144,104.5,-217.7,106.5,-221
+l0 -0
+c5.3,-9.3,12,-14,20,-14
+H400000v40H845.2724
+s-225.272,467,-225.272,467s-235,486,-235,486c-2.7,4.7,-9,7,-19,7
+c-6,0,-10,-1,-12,-3s-194,-422,-194,-422s-65,47,-65,47z
+M834 80h400000v40h-400000z"></path></svg></span></span></span><span class="vlist-s">​</span></span><span class="vlist-r"><span class="vlist" style="height:0.1266em;"><span></span></span></span></span></span></span></span></span><span class="vlist-s">​</span></span><span class="vlist-r"><span class="vlist" style="height:0.686em;"><span></span></span></span></span></span><span class="mclose nulldelimiter"></span></span></span></span></span></span></pre>
+<h2>Nested Elements</h2>
+<h3>Nested Code and Lists</h3>
+<ol>
+<li>
+<p>Ordered list item</p>
+<ul>
+<li>
+<p>Unordered subitem</p>
+<pre>console.log("Nested code block");
+</pre>
+</li>
+</ul>
+</li>
+<li>
+<p>This is a nested math</p>
+<pre class="math"><span class="katex-display"><span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML" display="block"><semantics><mrow><mi>y</mi><mo>=</mo><msup><mi>x</mi><mn>2</mn></msup></mrow><annotation encoding="application/x-tex">y=x^2</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.625em;vertical-align:-0.1944em;"></span><span class="mord mathnormal" style="margin-right:0.03588em;">y</span><span class="mspace" style="margin-right:0.2778em;"></span><span class="mrel">=</span><span class="mspace" style="margin-right:0.2778em;"></span></span><span class="base"><span class="strut" style="height:0.8641em;"></span><span class="mord"><span class="mord mathnormal">x</span><span class="msupsub"><span class="vlist-t"><span class="vlist-r"><span class="vlist" style="height:0.8641em;"><span style="top:-3.113em;margin-right:0.05em;"><span class="pstrut" style="height:2.7em;"></span><span class="sizing reset-size6 size3 mtight"><span class="mord mtight">2</span></span></span></span></span></span></span></span></span></span></span></span></pre>
+</li>
+<li>
+This is a inline math<span class="math"><span class="katex"><span class="katex-mathml"><math xmlns="http://www.w3.org/1998/Math/MathML"><semantics><mrow><mn>123</mn></mrow><annotation encoding="application/x-tex">123</annotation></semantics></math></span><span class="katex-html" aria-hidden="true"><span class="base"><span class="strut" style="height:0.6444em;"></span><span class="mord">123</span></span></span></span></span>
+</li>
+<li>
+<p>This is a line table</p>
+<table>
+<tbody>
+<tr>
+<td>
+<p>1</p>
+</td>
+<td>
+<p>2</p>
+</td>
+<td>
+<p>3</p>
+</td>
+</tr>
+<tr>
+<td>
+<p>4</p>
+</td>
+<td>
+<p>5</p>
+</td>
+<td>
+<p>6</p>
+</td>
+</tr>
+<tr>
+<td>
+<p>7</p>
+</td>
+<td>
+<p>8</p>
+</td>
+<td>
+<p>9</p>
+</td>
+</tr>
+</tbody>
+</table>
+</li>
+</ol>
+<h2>Special Characters</h2>
+<p>Escape sequences for special characters: * _ \` [ ] ( ) # + - .</p>
+<h2>HTML in Markdown</h2>
+<p>This is a HTML block inside Markdown.</p>
+<h2>Highlight Text</h2>
+<p>Highlight <span style="background-color: rgb(255, 102, 102);">text</span> is here</p>
+<h2>Colored Text</h2>
+<p>Colored <span style="color: rgb(255, 32, 32)">text</span> is here</p>
+<h2>Task Lists</h2>
+<ul>
+<li>
+Completed item
+</li>
+<li>
+Incomplete item
+</li>
+</ul>
+<h2>Strikethrough</h2>
+<p><span style="text-decoration: line-through">This text is strikethrough.</span></p>
+<h2>Recursive Elements</h2>
+<h3>Recursive Links and Emphasis</h3>
+<p><strong><a href="https://example.com" rel="noopener noreferrer nofollow">Bold link</a></strong></p>
+<h3>Recursive Emphasis</h3>
+<p><strong><em>Bold and nested italic within bold.</em></strong></p>
+<h2>Image</h2>
+<p>IMAGE_PLACEHOLDER</p>
+<h2>Citation</h2>
+<p>CITATION_PLACEHOLDER</p>
+<h2>Edge Cases</h2>
+<h3>Empty Link</h3>
+<p><a href="https://" rel="noopener noreferrer nofollow">Link</a></p>
+<h3>Zotero Link</h3>
+<p><a href="zotero://note/u/123456" rel="noopener noreferrer nofollow">Zotero Link</a></p>
+<h3>Lone Asterisk</h3>
+<ul>
+<li>
+This should not be italic.
+</li>
+</ul>
+<h3>Broken Lists</h3>
+<ul>
+<li>
+<p>Item 1</p>
+<ul>
+<li>
+<p>Item 2</p>
+<p>Continuation of item 2 without proper indentation.</p>
+</li>
+</ul>
+</li>
+</ul>
+<h3>Long Text Wrapping</h3>
+<p>This is a very long paragraph that does not have any line breaks and is intended to test how the Markdown engine handles text wrapping when there are no explicit line breaks within the text.</p>
+<hr>
+<h2>Conclusion</h2>
+<p>This document contains a wide range of Markdown elements, including headers, lists, blockquotes, inline and block code, tables, images, links, math, and special characters. It also tests recursive and edge cases to ensure the Markdown engine is robust.</p>
+</div>`;
+    // debug(preview);
+    // If the template changes, update the expected value by copying the expected value
+    // new ClipboardHelper().addText(parseTemplateString(preview)).copy();
+    assert.equal(preview, expected);
+    addon.api.template.removeTemplate(key);
+  });
+
+  it("api.template.runTextTemplate", async function () {
+    addon.api.template.setTemplate({
+      name: "[text]Test",
+      text: "<h1>Test</h1>\n<p>${targetNoteItem.id}</p>",
+    });
+    const note = new Zotero.Item("note");
+    await note.saveTx();
+    const html = await addon.api.template.runTextTemplate("[text]Test", {
+      targetNoteId: note.id,
+    });
+    assert.equal(html, `<h1>Test</h1>\n<p>${note.id}</p>`);
+    await Zotero.Items.erase(note.id);
+    addon.api.template.removeTemplate("[text]Test");
+  });
+
+  it("api.template.runItemTemplate", async function () {
+    // Also test the use of Markdown pragma
+    addon.api.template.setTemplate({
+      name: "[item]Test",
+      text: `
+// @beforeloop-begin
+// @use-markdown
+# Hi! This only renders once
+// @beforeloop-end
+// @default-begin
+<p>Title: <span style="color: #ffcb00">]\${topItem.getField("title")}</span></p>
+\${{
+    const note = Zotero.Items.get(targetNoteItem.id);
+    return "<p>" + note.id + "</p>";
+}}$
+// @default-end
+// @afterloop-begin
+> Done! But Markdown is not rendered correctly. Try to add 
+\`// @use-markdown\` pragma before this line.
+// @afterloop-end
+`,
+    });
+    const items = [];
+    for (let i = 0; i < 3; i++) {
+      const item = new Zotero.Item("book");
+      item.setField("title", `Title ${i}`);
+      await item.saveTx();
+      items.push(item);
+    }
+    const note = new Zotero.Item("note");
+    await note.saveTx();
+    const html = await addon.api.template.runItemTemplate("[item]Test", {
+      itemIds: items.map((item) => item.id),
+      targetNoteId: note.id,
+    });
+    // new ClipboardHelper().addText(parseTemplateString(html)).copy();
+    const expected = `<h1>Hi! This only renders once</h1>
+<p>Title: <span style="color: #ffcb00">]Title 0</span></p>
+<p>6</p>
+<p>Title: <span style="color: #ffcb00">]Title 1</span></p>
+<p>6</p>
+<p>Title: <span style="color: #ffcb00">]Title 2</span></p>
+<p>6</p>
+> Done! But Markdown is not rendered correctly. Try to add 
+`;
+    assert.equal(html, expected);
+    for (const item of items) {
+      await Zotero.Items.erase(item.id);
+    }
+    await Zotero.Items.erase(note.id);
+    addon.api.template.removeTemplate("[item]Test");
+  });
+});
+
+function importTemplate() {
+  const shareCode = `
+# This template is specifically for importing/sharing, using better 
+# notes 'import from clipboard': copy the content and
+# goto Zotero menu bar, click Tools->New Template from Clipboard.  
+# Do not copy-paste this to better notes template editor directly.
+name: "[text]TestGen"
+zoteroVersion: "7.0.12-beta.1+31bbf2acf"
+pluginVersion: "2.2.3-beta.2"
+savedAt: "2025-01-06T09:12:14.939Z"
+content: |-
+${getNoteContent()
+  .split("\n")
+  .map((line) => `  ${line}`)
+  .join("\n")}
+`;
+  return getAddon().hooks.onImportTemplateFromClipboard(shareCode, {
+    quiet: true,
+  });
+}

test/utils/global.ts

@@ -0,0 +1,8 @@
+import { config } from "../../package.json";
+
+export { getAddon };
+
+function getAddon(): import("../../src/addon").default {
+  // @ts-ignore - plugin instance
+  return Zotero[config.addonRef];
+}

test/utils/io.ts

@@ -0,0 +1,16 @@
+export async function getTempDirectory() {
+  let path = "";
+  let attempts = 3;
+  const zoteroTmpDirPath = Zotero.getTempDirectory().path;
+  while (attempts--) {
+    path = PathUtils.join(zoteroTmpDirPath, Zotero.Utilities.randomString());
+    try {
+      await IOUtils.makeDirectory(path, { ignoreExisting: false });
+      break;
+    } catch (e) {
+      if (!attempts) throw e; // Throw on last attempt
+    }
+  }
+
+  return path;
+}

test/utils/note.ts

@@ -0,0 +1,250 @@
+export function getNoteContent() {
+  return `<div data-schema-version="9"><h1>Markdown Test Document</h1>
+<h2>Headers</h2>
+<h1>H1 Header</h1>
+<h2>H2 Header</h2>
+<h3>H3 Header</h3>
+<h4>H4 Header</h4>
+<h5>H5 Header</h5>
+<h6>H6 Header</h6>
+<h2>Emphasis</h2>
+<p><em>This text is italicized.</em> <em>This text is also italicized.</em></p>
+<p><strong>This text is bold.</strong> <strong>This text is also bold.</strong></p>
+<p><strong><em>This text is bold and italicized.</em></strong> <strong><em>This text is also bold and italicized.</em></strong></p>
+<h2>Links</h2>
+<p><a href="https://example.com" title="Title" rel="noopener noreferrer nofollow">Link with title</a> <a href="https://example.com" rel="noopener noreferrer nofollow">Link without title</a></p>
+<h2>Images</h2>
+<p></p>
+<h2>Blockquotes</h2>
+<blockquote>
+<p>This is a blockquote.</p>
+<blockquote>
+<p>Nested blockquote.</p>
+</blockquote>
+<p>Back to the outer blockquote.</p>
+</blockquote>
+<h2>Lists</h2>
+<h3>Unordered List</h3>
+<ul>
+<li>
+<p>Item 1</p>
+<ul>
+<li>
+<p>Subitem 1.1</p>
+<ul>
+<li>
+Subitem 1.1.1
+</li>
+</ul>
+</li>
+</ul>
+</li>
+<li>
+Item 2
+</li>
+</ul>
+<h3>Ordered List</h3>
+<ol>
+<li>
+<p>First item</p>
+<ol>
+<li>
+<p>Subitem 1.1</p>
+<ol>
+<li>
+Subitem 1.1.1
+</li>
+</ol>
+</li>
+</ol>
+</li>
+<li>
+Second item
+</li>
+</ol>
+<h2>Code</h2>
+<h3>Inline Code</h3>
+<p>Here is some <code>inline code</code>.</p>
+<h3>Code Block</h3>
+<pre>def hello_world():
+ &nbsp; &nbsp;print("Hello, world!")
+</pre>
+<h2>Horizontal Rules</h2>
+<hr>
+<p>This is text between horizontal rules</p>
+<hr>
+<h2>Tables</h2>
+<table>
+<tbody>
+<tr>
+<th>
+<p>Header 1</p>
+</th>
+<th>
+<p>Header 2</p>
+</th>
+<th>
+<p>Header 3</p>
+</th>
+</tr>
+<tr>
+<td>
+<p>Row 1</p>
+</td>
+<td>
+<p>Data 1.2</p>
+</td>
+<td>
+<p>Data 1.3</p>
+</td>
+</tr>
+<tr>
+<td>
+<p>Row 2</p>
+</td>
+<td>
+<p>Data 2.2</p>
+</td>
+<td>
+<p>Data 2.3</p>
+</td>
+</tr>
+</tbody>
+</table>
+<h2>Math</h2>
+<h3>Inline Math</h3>
+<p>This is an inline math equation: <span class="math">$E = mc^2$</span>.</p>
+<h3>Block Math</h3>
+<p>Below is a block math equation:</p>
+<pre class="math">$$\\\\int_a^b f(x) \\\\, dx = F(b) - F(a)$$</pre>
+<h3>Complex Math</h3>
+<p>Solve the quadratic equation:</p>
+<pre class="math">$$x = \\\\frac{-b \\\\pm \\\\sqrt{b^2 - 4ac}}{2a}$$</pre>
+<h2>Nested Elements</h2>
+<h3>Nested Code and Lists</h3>
+<ol>
+<li>
+<p>Ordered list item</p>
+<ul>
+<li>
+<p>Unordered subitem</p>
+<pre>console.log("Nested code block");
+</pre>
+</li>
+</ul>
+</li>
+<li>
+<p>This is a nested math</p>
+<pre class="math">$$y=x^2$$</pre>
+</li>
+<li>
+This is a inline math<span class="math">$123$</span>
+</li>
+<li>
+<p>This is a line table</p>
+<table>
+<tbody>
+<tr>
+<td>
+<p>1</p>
+</td>
+<td>
+<p>2</p>
+</td>
+<td>
+<p>3</p>
+</td>
+</tr>
+<tr>
+<td>
+<p>4</p>
+</td>
+<td>
+<p>5</p>
+</td>
+<td>
+<p>6</p>
+</td>
+</tr>
+<tr>
+<td>
+<p>7</p>
+</td>
+<td>
+<p>8</p>
+</td>
+<td>
+<p>9</p>
+</td>
+</tr>
+</tbody>
+</table>
+</li>
+</ol>
+<h2>Special Characters</h2>
+<p>Escape sequences for special characters: * _ \\\` [ ] ( ) # + - .</p>
+<h2>HTML in Markdown</h2>
+<p>This is a HTML block inside Markdown.</p>
+<h2>Highlight Text</h2>
+<p>Highlight <span style="background-color: rgba(255, 102, 102, 0.5)">text</span> is here</p>
+<h2>Colored Text</h2>
+<p>Colored <span style="color: rgb(255, 32, 32)">text</span> is here</p>
+<h2>Task Lists</h2>
+<ul>
+<li>
+Completed item
+</li>
+<li>
+Incomplete item
+</li>
+</ul>
+<h2>Strikethrough</h2>
+<p><span style="text-decoration: line-through">This text is strikethrough.</span></p>
+<h2>Recursive Elements</h2>
+<h3>Recursive Links and Emphasis</h3>
+<p><strong><a href="https://example.com" rel="noopener noreferrer nofollow">Bold link</a></strong></p>
+<h3>Recursive Emphasis</h3>
+<p><strong><em>Bold and nested italic within bold.</em></strong></p>
+<h2>Image</h2>
+<p>IMAGE_PLACEHOLDER</p>
+<h2>Citation</h2>
+<p>CITATION_PLACEHOLDER</p>
+<h2>Edge Cases</h2>
+<h3>Empty Link</h3>
+<p><a href="https://" rel="noopener noreferrer nofollow">Link</a></p>
+<h3>Zotero Link</h3>
+<p><a href="zotero://note/u/123456" rel="noopener noreferrer nofollow">Zotero Link</a></p>
+<h3>Lone Asterisk</h3>
+<ul>
+<li>
+This should not be italic.
+</li>
+</ul>
+<h3>Broken Lists</h3>
+<ul>
+<li>
+<p>Item 1</p>
+<ul>
+<li>
+<p>Item 2</p>
+<p>Continuation of item 2 without proper indentation.</p>
+</li>
+</ul>
+</li>
+</ul>
+<h3>Long Text Wrapping</h3>
+<p>This is a very long paragraph that does not have any line breaks and is intended to test how the Markdown engine handles text wrapping when there are no explicit line breaks within the text.</p>
+<hr>
+<h2>Conclusion</h2>
+<p>This document contains a wide range of Markdown elements, including headers, lists, blockquotes, inline and block code, tables, images, links, math, and special characters. It also tests recursive and edge cases to ensure the Markdown engine is robust.</p>
+</div>`;
+}
+
+export function parseTemplateString(input: string): string {
+  return input
+    .replace(/\\/g, "\\\\") // Escape backslashes
+    .replace(/`/g, "\\`") // Escape backticks
+    .replace(/\$/g, "\\$") // Escape dollar signs
+    .replace(/{/g, "\\{") // Escape opening braces
+    .replace(/}/g, "\\}"); // Escape closing braces
+}

typings/prefs.d.ts

@@ -0,0 +1,26 @@
+// Generated by zotero-plugin-scaffold
+/* prettier-ignore */
+/* eslint-disable */
+// @ts-nocheck
+
+// prettier-ignore
+declare namespace _ZoteroTypes {
+  interface Prefs {
+    PluginPrefsMap: {
+      "syncNoteIds": string;
+      "syncPeriodSeconds": number;
+      "syncAttachmentFolder": string;
+      "autoAnnotation": boolean;
+      "insertLinkPosition": string;
+      "workspace.outline.expandLevel": number;
+      "workspace.outline.keepLinks": boolean;
+      "editor.noteLinkPreviewType": string;
+      "editor.useMagicKey": boolean;
+      "editor.useMarkdownPaste": boolean;
+      "openNote.takeover": boolean;
+      "openNote.defaultAsWindow": boolean;
+      "exportNotes.takeover": boolean;
+      "annotationNote.enableTagSync": boolean;
+    };
+  }
+}

zotero-plugin.config.ts

@@ -52,10 +52,9 @@ export default defineConfig({
         target: ["firefox115"],
       },
     ],
-    // prefs: {
-    //   prefix: pkg.config.prefsPrefix,
-    //   dts: false,
-    // },
+    prefs: {
+      prefix: pkg.config.prefsPrefix,
+    },
     hooks: {
       "build:bundle": (ctx) => {
         return replaceInFile({