add: user guide

fix: #1005

addon/locale/en-US/addon.ftl

@@ -17,7 +17,7 @@ menuAddReaderNote-newTemplateNote = New Item Note from Template
 
 menuEditor-resizeImage = Resize Image
 
-templateEditor-templateName = Template Name
+menuHelp-openUserGuide = Open Better Notes User Guide
 
 editor-resizeImage-title = Resize Image
 editor-resizeImage-prompt = Resize image width to:
@@ -81,3 +81,37 @@ alert-notValidParentItemError = No valid parent item.
 alert-syncImportedNotes = Keep imported notes in sync with MarkDown files?
 alert-linkCreator-emptyNote = Cannot create link from/to an empty note. 
 alert-templateEditor-shouldImport = Seems like you are trying to directly save a note template share code. Do you want to import it as a template?
+
+userGuide-start-title = Welcome to Better Notes!
+userGuide-start-desc = Better Notes is a powerful note-taking tool that helps you organize your thoughts and ideas. It is designed to be simple and easy to use, yet flexible enough to handle complex note-taking tasks. This guide will help you get started with Better Notes and show you how to make the most of its features.
+userGuide-start-close = Remind me later
+userGuide-createNoteButton-title = Create a New Note
+userGuide-createNoteButton-desc = You can create a note here: blank or from a template.
+userGuide-createNote-title = Create a New Note
+userGuide-createNote-desc = Seems like you don't have any notes yet, let's create one.
+userGuide-createNote-next = Create Note
+userGuide-openNote-title = Open note
+userGuide-openNote-desc = You can open a note in Better Notes workspace tab by double-clicking it.
+userGuide-openNote-next = Open Note
+userGuide-workspace-title = Note Workspace Tab
+userGuide-workspace-desc = The note tab is where you can edit your note content, view the outline, and manage the relations.
+userGuide-workspaceEditor-title = Note Editor
+userGuide-workspaceEditor-desc = The editor supports rich text editing, code block, math block, and more.
+userGuide-workspaceEditorToolbar-title = Note Editor - Toolbar
+userGuide-workspaceEditorToolbar-desc = The toolbar provides quick access to common editing functions.
+    You can set the heading, text/background color, text style, insert link or reference here.
+userGuide-workspaceEditorLinkCreator-title = Note Editor - Link Creator
+userGuide-workspaceEditorLinkCreator-desc = You can create a link from/to another note via the link creator.
+userGuide-workspaceEditorMoreOptions-title = Note Editor - More Options
+userGuide-workspaceEditorMoreOptions-desc = Open the note in a new window, show it in the library, insert a template, copy the link, export the note, and more.
+userGuide-workspaceOutline-title = Outline
+userGuide-workspaceOutline-desc = The outline shows the structure of the note. You can navigate to a section by clicking on it.
+userGuide-workspaceOutlineMode-title = Outline Mode
+userGuide-workspaceOutlineMode-desc = Switch to outline mode to view the note structure in a more compact way.
+userGuide-workspaceOutlineSaveAs-title = Save As
+userGuide-workspaceOutlineSaveAs-desc = You can export the note to multiple formats, including PDF, Markdown, MS Word, mind map, and more.
+userGuide-workspaceNoteInfo-title = Note Info
+userGuide-workspaceNoteInfo-desc = You can view, edit, and manage the note's tags, relations, and links.
+userGuide-finish-title = We are all set!
+userGuide-finish-desc = Enjoy your note-taking journey with Better Notes!
+    You can always run this guide again from the Help menu.

addon/locale/en-US/templateEditor.ftl

@@ -1,4 +1,7 @@
 title = Template Editor
+
+templateName = Template Name
+
 previewContainer = 
     .label = Preview
 create = 

addon/locale/it-IT/addon.ftl

@@ -17,7 +17,7 @@ menuAddReaderNote-newTemplateNote = Nuova nota dell'elemento da template
 
 menuEditor-resizeImage = Ridimensiona immagine
 
-templateEditor-templateName = Nome template
+menuHelp-openUserGuide = Open Better Notes User Guide
 
 syncManager-noteName = Nome nota
 syncManager-lastSync = Ultima sincronizzazione
@@ -76,4 +76,38 @@ alert-notValidCollectionError = Si prega di scegliere una collezione valida.
 alert-notValidParentItemError = Nessun elemento genitore valido.
 alert-syncImportedNotes = Si desidera sincronizzare le note importate con i file markdown?
 alert-linkCreator-emptyNote = Cannot create link from/to an empty note. 
-alert-templateEditor-shouldImport = Sembra che tu stia cercando di salvare direttamente un codice di condivisione di un template di nota. Vuoi importarlo come template?
+alert-templateEditor-shouldImport = Sembra che tu stia cercando di salvare direttamente un codice di condivisione di un template di nota. Vuoi importarlo come template?
+
+userGuide-start-title = Welcome to Better Notes!
+userGuide-start-desc = Better Notes is a powerful note-taking tool that helps you organize your thoughts and ideas. It is designed to be simple and easy to use, yet flexible enough to handle complex note-taking tasks. This guide will help you get started with Better Notes and show you how to make the most of its features.
+userGuide-start-close = Remind me later
+userGuide-createNoteButton-title = Create a New Note
+userGuide-createNoteButton-desc = You can create a note here: blank or from a template.
+userGuide-createNote-title = Create a New Note
+userGuide-createNote-desc = Seems like you don't have any notes yet, let's create one.
+userGuide-createNote-next = Create Note
+userGuide-openNote-title = Open note
+userGuide-openNote-desc = You can open a note in Better Notes workspace tab by double-clicking it.
+userGuide-openNote-next = Open Note
+userGuide-workspace-title = Note Workspace Tab
+userGuide-workspace-desc = The note tab is where you can edit your note content, view the outline, and manage the relations.
+userGuide-workspaceEditor-title = Note Editor
+userGuide-workspaceEditor-desc = The editor supports rich text editing, code block, math block, and more.
+userGuide-workspaceEditorToolbar-title = Note Editor - Toolbar
+userGuide-workspaceEditorToolbar-desc = The toolbar provides quick access to common editing functions.
+    You can set the heading, text/background color, text style, insert link or reference here.
+userGuide-workspaceEditorLinkCreator-title = Note Editor - Link Creator
+userGuide-workspaceEditorLinkCreator-desc = You can create a link from/to another note via the link creator.
+userGuide-workspaceEditorMoreOptions-title = Note Editor - More Options
+userGuide-workspaceEditorMoreOptions-desc = Open the note in a new window, show it in the library, insert a template, copy the link, export the note, and more.
+userGuide-workspaceOutline-title = Outline
+userGuide-workspaceOutline-desc = The outline shows the structure of the note. You can navigate to a section by clicking on it.
+userGuide-workspaceOutlineMode-title = Outline Mode
+userGuide-workspaceOutlineMode-desc = Switch to outline mode to view the note structure in a more compact way.
+userGuide-workspaceOutlineSaveAs-title = Save As
+userGuide-workspaceOutlineSaveAs-desc = You can export the note to multiple formats, including PDF, Markdown, MS Word, mind map, and more.
+userGuide-workspaceNoteInfo-title = Note Info
+userGuide-workspaceNoteInfo-desc = You can view, edit, and manage the note's tags, relations, and links.
+userGuide-finish-title = We are all set!
+userGuide-finish-desc = Enjoy your note-taking journey with Better Notes!
+    You can always run this guide again from the Help menu.

addon/locale/it-IT/templateEditor.ftl

@@ -1,4 +1,7 @@
 title = Editor dei template
+
+templateName = Nome template
+
 previewContainer = 
     .label = Anteprima
 create = 

addon/locale/ru-RU/addon.ftl

@@ -17,7 +17,7 @@ menuAddReaderNote-newTemplateNote=Новая элементная Заметка
 
 menuEditor-resizeImage=Изменить размер изображения
 
-templateEditor-templateName = Имя шаблона
+menuHelp-openUserGuide = Open Better Notes User Guide
 
 editor-resizeImage-title = Resize Image
 editor-resizeImage-prompt = Resize image width to:
@@ -81,3 +81,37 @@ alert-notValidParentItemError=Нет валидного родительског
 alert-syncImportedNotes = Синхронизировать импортированные заметки с файлами MarkDown?
 alert-linkCreator-emptyNote = Cannot create link from/to an empty note. 
 alert-templateEditor-shouldImport = Вы пытаетесь сохранить код шаблона заметки. Хотите импортировать его как шаблон?
+
+userGuide-start-title = Welcome to Better Notes!
+userGuide-start-desc = Better Notes is a powerful note-taking tool that helps you organize your thoughts and ideas. It is designed to be simple and easy to use, yet flexible enough to handle complex note-taking tasks. This guide will help you get started with Better Notes and show you how to make the most of its features.
+userGuide-start-close = Remind me later
+userGuide-createNoteButton-title = Create a New Note
+userGuide-createNoteButton-desc = You can create a note here: blank or from a template.
+userGuide-createNote-title = Create a New Note
+userGuide-createNote-desc = Seems like you don't have any notes yet, let's create one.
+userGuide-createNote-next = Create Note
+userGuide-openNote-title = Open note
+userGuide-openNote-desc = You can open a note in Better Notes workspace tab by double-clicking it.
+userGuide-openNote-next = Open Note
+userGuide-workspace-title = Note Workspace Tab
+userGuide-workspace-desc = The note tab is where you can edit your note content, view the outline, and manage the relations.
+userGuide-workspaceEditor-title = Note Editor
+userGuide-workspaceEditor-desc = The editor supports rich text editing, code block, math block, and more.
+userGuide-workspaceEditorToolbar-title = Note Editor - Toolbar
+userGuide-workspaceEditorToolbar-desc = The toolbar provides quick access to common editing functions.
+    You can set the heading, text/background color, text style, insert link or reference here.
+userGuide-workspaceEditorLinkCreator-title = Note Editor - Link Creator
+userGuide-workspaceEditorLinkCreator-desc = You can create a link from/to another note via the link creator.
+userGuide-workspaceEditorMoreOptions-title = Note Editor - More Options
+userGuide-workspaceEditorMoreOptions-desc = Open the note in a new window, show it in the library, insert a template, copy the link, export the note, and more.
+userGuide-workspaceOutline-title = Outline
+userGuide-workspaceOutline-desc = The outline shows the structure of the note. You can navigate to a section by clicking on it.
+userGuide-workspaceOutlineMode-title = Outline Mode
+userGuide-workspaceOutlineMode-desc = Switch to outline mode to view the note structure in a more compact way.
+userGuide-workspaceOutlineSaveAs-title = Save As
+userGuide-workspaceOutlineSaveAs-desc = You can export the note to multiple formats, including PDF, Markdown, MS Word, mind map, and more.
+userGuide-workspaceNoteInfo-title = Note Info
+userGuide-workspaceNoteInfo-desc = You can view, edit, and manage the note's tags, relations, and links.
+userGuide-finish-title = We are all set!
+userGuide-finish-desc = Enjoy your note-taking journey with Better Notes!
+    You can always run this guide again from the Help menu.

addon/locale/ru-RU/templateEditor.ftl

@@ -1,4 +1,7 @@
 title = Редактор шаблонов
+
+templateName = Имя шаблона
+
 previewContainer = 
     .label = Предпросмотр
 create = 

addon/locale/tr-TR/addon.ftl

@@ -17,7 +17,7 @@ menuAddReaderNote-newTemplateNote = Şablondan Yeni Öge Notu
 
 menuEditor-resizeImage = Resmi Boyutlandır
 
-templateEditor-templateName = Şablon Adı
+menuHelp-openUserGuide = Open Better Notes User Guide
 
 editor-resizeImage-title = Resmi Boyutlandır
 editor-resizeImage-prompt = Resmi Şuna Boyutlandır:
@@ -80,4 +80,38 @@ alert-notValidCollectionError = Lütfen geçerli bir koleksiyon seçin.
 alert-notValidParentItemError = Geçerli üst öge yok.
 alert-syncImportedNotes = İçe aktarılmış notları Markdown dosyalarıyla senkron tutmak ister misiniz?
 alert-linkCreator-emptyNote = Cannot create link from/to an empty note. 
-alert-templateEditor-shouldImport = Şablon kodunu doğrudan kaydetmeye çalışıyorsunuz gibi görünüyor. Şablon olarak içe aktarmak ister misiniz?
+alert-templateEditor-shouldImport = Şablon kodunu doğrudan kaydetmeye çalışıyorsunuz gibi görünüyor. Şablon olarak içe aktarmak ister misiniz?
+
+userGuide-start-title = Welcome to Better Notes!
+userGuide-start-desc = Better Notes is a powerful note-taking tool that helps you organize your thoughts and ideas. It is designed to be simple and easy to use, yet flexible enough to handle complex note-taking tasks. This guide will help you get started with Better Notes and show you how to make the most of its features.
+userGuide-start-close = Remind me later
+userGuide-createNoteButton-title = Create a New Note
+userGuide-createNoteButton-desc = You can create a note here: blank or from a template.
+userGuide-createNote-title = Create a New Note
+userGuide-createNote-desc = Seems like you don't have any notes yet, let's create one.
+userGuide-createNote-next = Create Note
+userGuide-openNote-title = Open note
+userGuide-openNote-desc = You can open a note in Better Notes workspace tab by double-clicking it.
+userGuide-openNote-next = Open Note
+userGuide-workspace-title = Note Workspace Tab
+userGuide-workspace-desc = The note tab is where you can edit your note content, view the outline, and manage the relations.
+userGuide-workspaceEditor-title = Note Editor
+userGuide-workspaceEditor-desc = The editor supports rich text editing, code block, math block, and more.
+userGuide-workspaceEditorToolbar-title = Note Editor - Toolbar
+userGuide-workspaceEditorToolbar-desc = The toolbar provides quick access to common editing functions.
+    You can set the heading, text/background color, text style, insert link or reference here.
+userGuide-workspaceEditorLinkCreator-title = Note Editor - Link Creator
+userGuide-workspaceEditorLinkCreator-desc = You can create a link from/to another note via the link creator.
+userGuide-workspaceEditorMoreOptions-title = Note Editor - More Options
+userGuide-workspaceEditorMoreOptions-desc = Open the note in a new window, show it in the library, insert a template, copy the link, export the note, and more.
+userGuide-workspaceOutline-title = Outline
+userGuide-workspaceOutline-desc = The outline shows the structure of the note. You can navigate to a section by clicking on it.
+userGuide-workspaceOutlineMode-title = Outline Mode
+userGuide-workspaceOutlineMode-desc = Switch to outline mode to view the note structure in a more compact way.
+userGuide-workspaceOutlineSaveAs-title = Save As
+userGuide-workspaceOutlineSaveAs-desc = You can export the note to multiple formats, including PDF, Markdown, MS Word, mind map, and more.
+userGuide-workspaceNoteInfo-title = Note Info
+userGuide-workspaceNoteInfo-desc = You can view, edit, and manage the note's tags, relations, and links.
+userGuide-finish-title = We are all set!
+userGuide-finish-desc = Enjoy your note-taking journey with Better Notes!
+    You can always run this guide again from the Help menu.

addon/locale/tr-TR/templateEditor.ftl

@@ -1,4 +1,7 @@
 title = Şablon Düzenleyici
+
+templateName = Şablon Adı
+
 previewContainer = 
     .label = Ön İzle
 create = 

addon/locale/zh-CN/addon.ftl

@@ -17,7 +17,7 @@ menuAddReaderNote-newTemplateNote=从模板新建条目子笔记
 
 menuEditor-resizeImage=缩放图片
 
-templateEditor-templateName = 模板名称
+menuHelp-openUserGuide = 打开Better Notes用户指南
 
 editor-resizeImage-title = 缩放图片
 editor-resizeImage-prompt = 缩放图片宽度为：
@@ -81,3 +81,37 @@ alert-notValidParentItemError=无效的父条目。
 alert-syncImportedNotes = 保持导入的笔记与 MarkDown 文件同步？
 alert-linkCreator-emptyNote = 无法从/向空笔记创建链接。
 alert-templateEditor-shouldImport = 似乎您正在尝试直接保存一个笔记模板分享代码。您想要将其导入为模板吗？
+
+userGuide-start-title = 欢迎使用Better Notes！
+userGuide-start-desc = Better Notes是一个强大的笔记工具，帮助您组织思想和想法。它设计简单易用，但足够灵活，能够处理复杂的笔记任务。本指南将帮助您开始使用Better Notes，并向您展示如何充分利用其功能。
+userGuide-start-close = 稍后提醒我
+userGuide-createNoteButton-title = 创建新笔记
+userGuide-createNoteButton-desc = 您可以在这里创建笔记：空白或从模板创建。
+userGuide-createNote-title = 创建新笔记
+userGuide-createNote-desc = 看来您还没有任何笔记，让我们创建一个。
+userGuide-createNote-next = 创建笔记
+userGuide-openNote-title = 打开笔记
+userGuide-openNote-desc = 您可以通过双击在Better Notes工作区标签中打开一个笔记。
+userGuide-openNote-next = 打开笔记
+userGuide-workspace-title = 笔记工作区标签
+userGuide-workspace-desc = 笔记标签是您可以编辑笔记内容、查看大纲和管理关系的地方。
+userGuide-workspaceEditor-title = 笔记编辑器
+userGuide-workspaceEditor-desc = 编辑器支持富文本编辑、代码块、数学块等。
+userGuide-workspaceEditorToolbar-title = 笔记编辑器 - 工具栏
+userGuide-workspaceEditorToolbar-desc = 工具栏提供对常见编辑功能的快速访问。
+    您可以在这里设置标题、文本/背景颜色、文本样式、插入链接或引用。
+userGuide-workspaceEditorLinkCreator-title = 笔记编辑器 - 链接精灵
+userGuide-workspaceEditorLinkCreator-desc = 您可以通过链接精灵创建从/到另一个笔记的链接。
+userGuide-workspaceEditorMoreOptions-title = 笔记编辑器 - 更多选项
+userGuide-workspaceEditorMoreOptions-desc = 在新窗口中打开笔记，显示在库中，插入模板，复制链接，导出笔记等。
+userGuide-workspaceOutline-title = 大纲
+userGuide-workspaceOutline-desc = 大纲显示了笔记的结构。您可以通过点击它来导航到一个部分。
+userGuide-workspaceOutlineMode-title = 大纲模式
+userGuide-workspaceOutlineMode-desc = 切换到大纲模式以不同的方式查看笔记结构。
+userGuide-workspaceOutlineSaveAs-title = 另存为
+userGuide-workspaceOutlineSaveAs-desc = 您可以将笔记导出为多种格式，包括PDF、Markdown、MS Word、思维导图等。
+userGuide-workspaceNoteInfo-title = 笔记信息
+userGuide-workspaceNoteInfo-desc = 您可以查看、编辑和管理笔记的标签、关系和链接。
+userGuide-finish-title = 准备完成！
+userGuide-finish-desc = 享受您的笔记旅程与Better Notes！
+    您可以随时从菜单栏 - 帮助再次运行此指南。

addon/locale/zh-CN/templateEditor.ftl

@@ -1,4 +1,7 @@
 title = 模板编辑器
+
+templateName = 模板名称
+
 previewContainer = 
     .label = 预览
 create = 

package.json

@@ -56,7 +56,7 @@
     "unist-util-visit": "^5.0.0",
     "unist-util-visit-parents": "^6.0.1",
     "yamljs": "^0.3.0",
-    "zotero-plugin-toolkit": "^2.3.31"
+    "zotero-plugin-toolkit": "^2.3.33"
   },
   "devDependencies": {
     "@esbuild-plugins/node-globals-polyfill": "^0.2.3",
@@ -84,7 +84,7 @@
     "replace-in-file": "^7.2.0",
     "typescript": "^5.3.3",
     "xslt3": "^2.6.0",
-    "zotero-plugin-scaffold": "^0.0.26",
+    "zotero-plugin-scaffold": "^0.0.32",
     "zotero-types": "^2.0.1"
   },
   "eslintConfig": {

src/addon.ts

@@ -14,6 +14,7 @@ import { createZToolkit } from "./utils/ztoolkit";
 
 class Addon {
   public data: {
+    uid: string;
     alive: boolean;
     // Env type, see build.js
     env: "development" | "production";
@@ -78,7 +79,11 @@ class Addon {
     };
     imageCache: Record<number, string>;
     readonly prompt?: Prompt;
+    hint: {
+      silent: boolean;
+    };
   } = {
+    uid: Zotero.Utilities.randomString(8),
     alive: true,
     env: __env__,
     ztoolkit: createZToolkit(),
@@ -124,6 +129,9 @@ class Addon {
     get prompt() {
       return ToolkitGlobal.getInstance().prompt.instance;
     },
+    hint: {
+      silent: false,
+    },
   };
   // Lifecycle hooks
   public hooks: typeof hooks;

src/hooks.ts

@@ -40,6 +40,7 @@ import { registerNoteRelation } from "./modules/workspace/relation";
 import { getPref, setPref } from "./utils/prefs";
 import { closeRelationWorker } from "./utils/relation";
 import { registerNoteLinkSection } from "./modules/workspace/link";
+import { showUserGuide } from "./modules/userGuide";
 
 async function onStartup() {
   await Promise.all([
@@ -71,7 +72,7 @@ async function onStartup() {
 
   setSyncing();
 
-  await onMainWindowLoad(window);
+  await onMainWindowLoad(Zotero.getMainWindow());
 }
 
 async function onMainWindowLoad(win: Window): Promise<void> {
@@ -93,6 +94,8 @@ async function onMainWindowLoad(win: Window): Promise<void> {
   patchViewItems(win);
 
   restoreNoteTabs();
+
+  showUserGuide(win);
 }
 
 async function onMainWindowUnload(win: Window): Promise<void> {
@@ -207,10 +210,10 @@ async function onOpenNote(
       openNotePreview(noteItem, workspaceUID, options);
       break;
     case "tab":
-      await openWorkspaceTab(noteItem, options);
+      return await openWorkspaceTab(noteItem, options);
       break;
     case "window":
-      await openWorkspaceWindow(noteItem, options);
+      return await openWorkspaceWindow(noteItem, options);
       break;
     case "builtin":
       ZoteroPane.openNoteWindow(noteId);
@@ -246,6 +249,8 @@ const onCreateNoteFromTemplate = createNoteFromTemplate;
 
 const onCreateNoteFromMD = createNoteFromMD;
 
+const onShowUserGuide = showUserGuide;
+
 // Add your hooks here. For element click, etc.
 // Keep in mind hooks only do dispatch. Don't add code that does real jobs in hooks.
 // Otherwise the code would be hard to read and maintain.
@@ -272,4 +277,5 @@ export default {
   onCreateNoteFromTemplate,
   onCreateNoteFromMD,
   restoreNoteTabs,
+  onShowUserGuide,
 };

src/modules/menu.ts

@@ -176,4 +176,11 @@ export function registerMenus(win: Window) {
         addon.hooks.onCreateNoteFromTemplate("item", "reader"),
     },
   );
+
+  ztoolkit.Menu.register("menuHelp", {
+    tag: "menuitem",
+    label: getString("menuHelp-openUserGuide"),
+    icon: `chrome://${config.addonRef}/content/icons/favicon.png`,
+    commandListener: () => addon.hooks.onShowUserGuide(win, true),
+  });
 }

src/modules/sync/api.ts

@@ -34,12 +34,12 @@ function initSyncList() {
   setPref("syncNoteIds", JSON.stringify(keys));
 }
 
-function getSyncNoteIds(): number[] {
+async function getSyncNoteIds() {
   const keys = addon.data.sync.data?.getKeys();
   if (!keys) {
     return [];
   }
-  return Zotero.Items.get(keys)
+  return (await Zotero.Items.getAsync(keys))
     .filter((item) => item.isNote())
     .map((item) => item.id);
 }

src/modules/sync/hooks.ts

@@ -55,7 +55,7 @@ async function callSyncing(
     addon.data.sync.lock = true;
     let skippedCount = 0;
     if (!items || !items.length) {
-      items = Zotero.Items.get(addon.api.sync.getSyncNoteIds());
+      items = Zotero.Items.get(await addon.api.sync.getSyncNoteIds());
     } else {
       items = items.filter((item) => addon.api.sync.isSyncNote(item.id));
     }

src/modules/sync/managerWindow.ts

@@ -140,10 +140,9 @@ const sortDataKeys = ["noteName", "lastSync", "filePath"] as Array<
   keyof SyncDataType
 >;
 
-function updateData() {
+async function updateData() {
   const sortKey = sortDataKeys[addon.data.sync.manager.columnIndex];
-  addon.data.sync.manager.data = addon.api.sync
+  addon.data.sync.manager.data = (await addon.api.sync.getSyncNoteIds())
-    .getSyncNoteIds()
     .map((noteId) => {
       const syncStatus = addon.api.sync.getSyncStatus(noteId);
       return {

src/modules/userGuide.ts

@@ -0,0 +1,240 @@
+import { config } from "../../package.json";
+import { getString } from "../utils/locale";
+import { clearPref, getPref, setPref } from "../utils/prefs";
+
+export { showUserGuide };
+
+const LATEST_TOUR_VERSION = 1;
+
+async function showUserGuide(win: Window, force = false) {
+  const doc = win.document;
+  if (!force && getPref("latestTourVersion") == LATEST_TOUR_VERSION) return;
+  setPref("latestTourVersion", LATEST_TOUR_VERSION);
+  const exampleNote = `
+# Welcome to Better Notes
+
+This note is created by the Better Notes user guide.
+You can always run the user guide again from menu Help -> Better Notes User Guide.
+
+## 📝 Introduction
+
+> Everything about note management. All in Zotero.
+
+Better Notes (BN) is a plugin for [Zotero](https://zotero.org).
+
+BN streamlines your workflows of:
+
+- paper reading
+- annotating
+- note taking
+- metadata analyzing
+- knowledge exporting
+- AI writing assistant
+
+and:
+
+- works out of the box
+- highly customizable
+- all in Zotero
+
+## 🚀 Get Started
+
+See the [Quick Start Guide](https://github.com/windingwind/zotero-better-notes?tab=readme-ov-file#-quick-start) to get started.
+
+## 📚 Resources
+
+You can find more information in the following links:
+
+- [Documentation](https://github.com/windingwind/zotero-better-notes)
+- [Issues](https://github.com/windingwind/zotero-better-notes/issues)
+- [Discussions](https://github.com/windingwind/zotero-better-notes/discussions)
+- [API](https://github.com/windingwind/zotero-better-notes?tab=readme-ov-file#-api)
+`;
+  let noteItem: Zotero.Item | undefined;
+  let tabID: string;
+  addon.data.hint.silent = true;
+  await new ztoolkit.Guide()
+    .addStep({
+      title: getString("userGuide-start-title"),
+      description: `<html:img src='chrome://${
+        config.addonRef
+      }/content/icons/knowledge-app.png' style="width: 300px; height: auto;"></html:img>
+    <html:span style='width: 300px; display: block; margin-top: 10px;'>
+      ${getString("userGuide-start-desc")}
+    </html:span>`,
+      position: "center",
+      showButtons: ["next", "close"],
+      closeBtnText: getString("userGuide-start-close"),
+      showProgress: true,
+      onCloseClick: () => {
+        clearPref("latestTourVersion");
+      },
+    })
+    .addStep({
+      title: getString("userGuide-createNoteButton-title"),
+      description: getString("userGuide-createNoteButton-desc"),
+      element: "#zotero-tb-note-add",
+      showButtons: ["prev", "next"],
+      showProgress: true,
+      onBeforeRender: async () => {
+        Zotero_Tabs.select("zotero-pane");
+        // @ts-ignore
+        ZoteroPane.collectionsView.selectLibrary(1);
+      },
+    })
+    .addStep({
+      title: getString("userGuide-createNote-title"),
+      description: getString("userGuide-createNote-desc"),
+      position: "center",
+      showButtons: ["next"],
+      showProgress: true,
+      nextBtnText: getString("userGuide-createNote-next"),
+      onBeforeRender: async ({ state }) => {
+        noteItem = (await Zotero.Items.getAll(1)).find((item) => item.isNote());
+        if (noteItem) {
+          ZoteroPane.selectItem(noteItem.id);
+          state.controller._currentIndex = 3;
+        }
+      },
+      onExit: async () => {
+        noteItem = new Zotero.Item("note");
+        noteItem.setNote(await addon.api.convert.md2html(exampleNote));
+        await noteItem.saveTx();
+      },
+    })
+    .addStep({
+      title: getString("userGuide-openNote-title"),
+      description: getString("userGuide-openNote-desc"),
+      element: "#item-tree-main-default .row.selected",
+      showButtons: ["next"],
+      nextBtnText: getString("userGuide-openNote-next"),
+      showProgress: true,
+    })
+    .addStep({
+      title: getString("userGuide-workspace-title"),
+      description: getString("userGuide-workspace-desc"),
+      position: "center",
+      showButtons: ["next"],
+      showProgress: true,
+      onBeforeRender: async ({ state: { step, controller } }) => {
+        tabID = (await addon.hooks.onOpenNote(noteItem!.id, "tab")) as string;
+
+        if (!tabID) {
+          controller.abort();
+          win.alert("Failed to open the note.");
+          return;
+        }
+      },
+    })
+    .addStep({
+      title: getString("userGuide-workspaceEditor-title"),
+      description: getString("userGuide-workspaceEditor-desc"),
+      element: () =>
+        doc.querySelector(`#${tabID} #${config.addonRef}-editor-main`)!,
+      position: "center",
+      showButtons: ["prev", "next"],
+      showProgress: true,
+    })
+    .addStep({
+      title: getString("userGuide-workspaceEditorToolbar-title"),
+      description: getString("userGuide-workspaceEditorToolbar-desc"),
+      element: () =>
+        (doc.querySelector(
+          `#${tabID} #${config.addonRef}-editor-main`,
+        ) as any)!._iframe.contentDocument.querySelector(".toolbar")!,
+      onMask: ({ mask }) => {
+        const elem = doc.querySelector(
+          `#${tabID} #${config.addonRef}-editor-main`,
+        ) as any;
+        mask(elem);
+        mask(elem._iframe.contentDocument.querySelector(".toolbar"));
+      },
+    })
+
+    .addStep({
+      title: getString("userGuide-workspaceEditorLinkCreator-title"),
+      description: getString("userGuide-workspaceEditorLinkCreator-desc"),
+      element: () =>
+        (doc.querySelector(
+          `#${tabID} #${config.addonRef}-editor-main`,
+        ) as any)!._iframe.contentDocument.querySelector(
+          ".toolbar .start button",
+        )!,
+      onMask: ({ mask }) => {
+        const elem = doc.querySelector(
+          `#${tabID} #${config.addonRef}-editor-main`,
+        ) as any;
+        mask(elem);
+        mask(
+          elem._iframe.contentDocument.querySelector(".toolbar .start button"),
+        );
+      },
+    })
+    .addStep({
+      title: getString("userGuide-workspaceEditorMoreOptions-title"),
+      description: getString("userGuide-workspaceEditorMoreOptions-desc"),
+      element: () =>
+        (doc.querySelector(
+          `#${tabID} #${config.addonRef}-editor-main`,
+        ) as any)!._iframe.contentDocument.querySelector(
+          ".toolbar .end .dropdown.more-dropdown",
+        )!,
+      onMask: ({ mask }) => {
+        const elem = doc.querySelector(
+          `#${tabID} #${config.addonRef}-editor-main`,
+        ) as any;
+        mask(elem);
+        mask(
+          elem._iframe.contentDocument.querySelector(
+            ".toolbar .end .dropdown.more-dropdown",
+          ),
+        );
+      },
+    })
+    .addStep({
+      title: getString("userGuide-workspaceOutline-title"),
+      description: getString("userGuide-workspaceOutline-desc"),
+      element: () => doc.querySelector(`#${tabID} bn-outline`)!,
+      position: "center",
+      showButtons: ["prev", "next"],
+      showProgress: true,
+    })
+    .addStep({
+      title: getString("userGuide-workspaceOutlineMode-title"),
+      description: getString("userGuide-workspaceOutlineMode-desc"),
+      element: () =>
+        doc.querySelector(
+          `#${tabID} bn-outline #${config.addonRef}-setOutline`,
+        )!,
+      showButtons: ["prev", "next"],
+      showProgress: true,
+    })
+    .addStep({
+      title: getString("userGuide-workspaceOutlineSaveAs-title"),
+      description: getString("userGuide-workspaceOutlineSaveAs-desc"),
+      element: () =>
+        doc.querySelector(
+          `#${tabID} bn-outline #${config.addonRef}-saveOutline`,
+        )!,
+      showButtons: ["prev", "next"],
+      showProgress: true,
+    })
+    .addStep({
+      title: getString("userGuide-workspaceNoteInfo-title"),
+      description: getString("userGuide-workspaceNoteInfo-desc"),
+      element: () => doc.querySelector(`#${tabID} bn-context`)!,
+      position: "center",
+      showButtons: ["prev", "next"],
+      showProgress: true,
+    })
+    .addStep({
+      title: getString("userGuide-finish-title"),
+      description: getString("userGuide-finish-desc"),
+      position: "center",
+      showButtons: ["prev", "close"],
+      showProgress: true,
+    })
+    .show(doc);
+
+  addon.data.hint.silent = false;
+}

src/modules/workspace/tab.ts

@@ -16,7 +16,7 @@ export async function openWorkspaceTab(
   if (currentTab) {
     if (select ?? true) Zotero_Tabs.select(currentTab.id);
     scrollTabEditorTo(item, options);
-    return;
+    return currentTab.id;
   }
   const { id, container } = Zotero_Tabs.add({
     type: TAB_TYPE,
@@ -32,6 +32,7 @@ export async function openWorkspaceTab(
     lineIndex,
     sectionName,
   });
+  return id;
 }
 
 let contextPaneOpen: boolean | undefined = undefined;

src/modules/workspace/window.ts

@@ -24,5 +24,5 @@ export async function openWorkspaceWindow(
   win.focus();
   // @ts-ignore
   win.updateTitle();
-  return workspace;
+  return win;
 }

src/utils/hint.ts

@@ -9,6 +9,7 @@ ProgressWindowHelper.setIconURI(
 );
 
 function showHint(text: string) {
+  if (addon.data.hint.silent) return;
   return new ProgressWindowHelper(PROGRESS_TITLE)
     .createLine({ text, progress: 100, type: "default" })
     .show();
@@ -19,6 +20,7 @@ async function showHintWithLink(
   linkText: string,
   linkCallback: (ev: MouseEvent) => any,
 ) {
+  if (addon.data.hint.silent) return;
   const progress = new ProgressWindowHelper(PROGRESS_TITLE)
     .createLine({ text, progress: 100, type: "default" })
     .show(-1);

src/utils/ztoolkit.ts

@@ -39,6 +39,7 @@ import { MenuManager } from "zotero-plugin-toolkit/dist/managers/menu";
 import { PromptManager } from "zotero-plugin-toolkit/dist/managers/prompt";
 import { ReaderTabPanelManager } from "zotero-plugin-toolkit/dist/managers/readerTabPanel";
 import { LargePrefHelper } from "zotero-plugin-toolkit/dist/helpers/largePref";
+import { GuideHelper } from "zotero-plugin-toolkit/dist/helpers/guide";
 
 class MyToolkit extends BasicTool {
   UI: UITool;
@@ -52,6 +53,7 @@ class MyToolkit extends BasicTool {
   VirtualizedTable: typeof VirtualizedTableHelper;
   Dialog: typeof DialogHelper;
   LargePref: typeof LargePrefHelper;
+  Guide: typeof GuideHelper;
 
   constructor() {
     super();
@@ -66,6 +68,7 @@ class MyToolkit extends BasicTool {
     this.VirtualizedTable = VirtualizedTableHelper;
     this.Dialog = DialogHelper;
     this.LargePref = LargePrefHelper;
+    this.Guide = GuideHelper;
   }
 
   unregisterAll() {