帮助文档 Obsidian 知识库 插件用户手册

Obsidian Vault of Help Documents - User Manual

Dragonfly Prototype Apps · Obsidian Vault of Help Documents...

版本 Version 1.0 · 2026-07-04

第一部分 中文手册

目录

1. 简介

2. 适用场景

3. 安装与启用

4. 运行环境与首次配置

5. 界面说明

6. 使用步骤

7. 参数说明

8. 输出结果

9. 常见问题与故障排除

10. 注意事项与已知限制

11. 参考资料

1. 简介

帮助文档 Obsidian 知识库(菜单名 Obsidian Vault of Help Documents...)是一款 Dragonfly 3D World 插件。它可以一键把您本机已安装的 Dragonfly 帮助文档,转换成一个对 [Obsidian](https://obsidian.md) 友好的本地知识库(vault),并直接打开。生成的知识库还内置一个离线检索插件:您用自然语言提问,它就用 BM25 算法把最相关的帮助段落排序展示,全程无需联网、无需 API Key、也无需下载任何模型。

插件读取的内容是 Dragonfly 自带的帮助文件——即 Dragonfly 安装目录下 <DragonflyInstall>\Help\Content 中由 MadCap Flare 导出的 HTML 主题页。转换过程会自动完成 HTML → Markdown 的全部工作:每个帮助主题生成一篇带 YAML 前言(标题 / 分类 / 标签 / 来源 / 别名)的笔记;内部超链接转为 [[双向链接]];表格转为 Markdown 表格;MadCap 的提示 / 注意 / 警告框转为 Obsidian 的 callout 提示块;可折叠的下拉块(dropdown)转为小标题;插图按内容哈希复制到 _attachments 目录并保留相对链接。随后插件生成导航(Home.md 总览页与每个分类一个 _MOC 索引页)、写入 .obsidian 配置,并把内置检索插件安装进去。

底层引擎与算法。HTML 解析使用 lxml(Dragonfly 自带的 Python 已经包含它),因此转换全程在 Dragonfly 自带 Python 的后台线程中完成,不需要安装虚拟环境(venv)、不需要外部程序、也不联网。内置检索插件是一个纯 CommonJS 的 Obsidian 社区插件(Dragonfly Help Search),在知识库加载时于内存中建立 BM25 检索索引(参数 K1=1.5、B=0.75,标题与分类权重加权 3 倍),对每篇笔记的正文进行分词后按查询相关度排序。这相当于“没有大模型的 RAG”——只做本地即时的检索(retrieval)那一半。

许可证要点。帮助内容来自您自己安装的 Dragonfly,不随插件分发;转换所用的引擎(lxml 与 Python 标准库)均为宽松许可(permissive)。内置的检索插件为本项目自带的纯 JavaScript 代码,无需构建步骤。

为什么按需生成而不是直接打包一份现成知识库?因为一份预先构建好的知识库体积可达上百 MB,而它的内容本就来自您机器上已有的 Dragonfly 帮助。改为在本机重建后:安装包只有几百 KB(纯代码);生成的知识库始终与您当前安装的 Dragonfly 版本一致(2025.1、2027.1……);每次升级 Dragonfly 后都可随时重新生成。

2. 适用场景

本插件适合任何希望像浏览本地维基一样查阅和检索 Dragonfly 帮助文档的场合:

• 快速定位说明:想找某个工具或工作流的说明时,在知识库里全文检索比在帮助浏览器里逐页翻找更快。
• 接入 Obsidian 的双向链接与图谱视图:帮助主题之间的交叉引用被转成 [[双向链接]],可以在 Obsidian 的关系图谱中直观地看到知识点之间的关联。
• 本地 RAG 检索语料:把知识库当作离线检索语料,用自然语言提出诸如“如何用 Cellpose 分割细胞”这类问题,内置检索插件会给出最相关的帮助段落。
• 离线、便携、可分发结构:由于内容来自您本机的 Dragonfly 安装,插件本身不携带上百 MB 的文件;生成的知识库是一个普通文件夹,可自行复制或备份。

3. 安装与启用

本插件随 Prototype Apps 完整安装包(Full Package) 分发,安装步骤如下:

1. 把安装包解压到任意较短的目录(如 C:\PL\,避免过深路径触发 Windows 260 字符路径上限)。

2. 双击运行 `Install_FullPackage.bat`。

3. 在弹出的对话框中选择核心安装模式(Fresh 全新 / Compatible 兼容),并在插件列表中勾选 `Obsidian Vault of Help Documents...`。

4. 点击 Install,等待控制台完成。

5. 完全退出并重启 Dragonfly(菜单只在启动时扫描)。

本插件在安装包中默认未勾选(默认状态:轻量菜单项开启、所有插件关闭)。因此首次安装时务必手动勾选它,或在安装后按下文方法启用。

重启后,插件出现在菜单 Prototype Apps ▸ Obsidian Vault of Help Documents...(在该菜单中归入 “Help & Documentation(帮助与文档)” 区段,排在数据处理类工具之后)。

以后修改勾选。最方便的方式是在 Dragonfly 内操作:打开 Developer ▸ Prototype Labs... ▸ Menu Item Manager,在底部的 “Prototype Apps (Full Package)” 列表里,每个应用一个勾选框——勾选=部署,取消=移除菜单项,重启 Dragonfly 生效。停用从不删除任何已生成内容,重新启用后立即可用。也可以随时重跑安装器(它会记住上次的勾选作为默认值)。

卸载。双击 `Uninstall_FullPackage.bat` 即可移除所有 Full Package 的菜单项与插件;它不会删除您已生成的知识库文件夹。

4. 运行环境与首次配置

本插件属于进程内(in-process)类型,运行在 Dragonfly 自带的 Python 之上。它与许多重型插件不同:

• 没有 “Setup Environment” 步骤:不需要搭建虚拟环境(venv),也不需要在首次使用时下载任何东西。所需的 lxml 已包含在 Dragonfly 自带的 Python 里。
• 无需 GPU:转换与检索都是纯 CPU、纯本地操作。
• 无需联网:整个转换流程离线完成;内置检索也在本地建立索引。
• 无需 WSL 或外部计算软件。

首次使用要做什么。打开面板后,直接点击 Convert & Build Vault(转换并建立知识库)。首次转换约需 10–90 秒(取决于帮助文档的规模),期间进度条依次显示“转换帮助文档 → 组装知识库”。生成的知识库默认写入以下位置:

%LOCALAPPDATA%\DragonflyPrototypeLabs\ObsidianHelpVault\vault

外部软件依赖:Obsidian。转换本身不需要任何外部程序,但要打开并浏览生成的知识库,需要安装免费的 Obsidian 应用(obsidian.md)。若面板未检测到 Obsidian,状态栏会提示您前往 obsidian.md 安装。

首次在 Obsidian 中打开该知识库时,Obsidian 会询问是否信任此文件夹。请点击 “Trust author and enable plugins(信任作者并启用插件)”,内置的 Dragonfly Help Search 检索插件才会加载。

失败时的替代方案。若 Open in Obsidian(在 Obsidian 中打开) 点击后没有反应(通常是尚未安装 Obsidian,或系统未注册 obsidian:// 协议),请改用 Open vault folder(打开知识库文件夹),然后把该文件夹拖到 Obsidian 的 “Open folder as vault(以文件夹作为知识库打开)” 上即可。

5. 界面说明

插件面板是一个可停靠(默认浮动)的 PyQt6 窗口,标题为 “Convert Dragonfly Help Documents to an Obsidian Vault”。自上而下的控件如下:

• 说明文字(顶部):简要说明插件的作用——从本机 Dragonfly 帮助文档构建本地知识库,并附带离线 BM25 检索。
• Help source(帮助来源)下拉框:列出自动检测到的 Dragonfly Help\Content 目录。检测优先级为:环境变量 DF_HELP_CONTENT(若设置)→ 当前正在运行的 Dragonfly 自带帮助(标记为 “Current Dragonfly”)→ 本机常见安装位置下检测到的其它 Dragonfly。若什么都没检测到,会显示 “(no Dragonfly help found — use Browse…)”。
• Browse…(浏览)按钮:手动选择某个 Dragonfly 安装的 Help\Content 文件夹(选中后会加到下拉框最前并自动选中)。
• Build to(构建到)输入框:知识库的输出目录,默认填入 %LOCALAPPDATA%\DragonflyPrototypeLabs\ObsidianHelpVault\vault。
• Change…(更改)按钮:更换输出目录;若所选目录名不是 vault,插件会自动在其下追加一个 vault 子目录。
• Convert & Build Vault(转换并建立知识库)按钮:核心按钮,启动后台转换。当没有可用的帮助来源时该按钮被禁用。
• 进度条:仅在转换过程中显示,范围 0–100。
• 状态栏:一行文字,报告当前状态、进度提示、完成统计或错误信息(错误时显示为红色)。
• 分隔线:界面下半部分是打开操作区。
• Open in Obsidian(在 Obsidian 中打开)按钮:通过 obsidian://open 协议请求 Obsidian 打开该知识库。
• Open vault folder(打开知识库文件夹)按钮:在文件资源管理器中打开知识库所在文件夹。
• Copy path(复制路径)按钮:把知识库路径复制到剪贴板。
• 底部使用提示:三步简明说明(点击构建 → 安装并在 Obsidian 中打开 → 用放大镜检索)。

构建完成前,三个“打开”按钮处于禁用状态;只有当知识库存在(或本次构建成功)且没有正在进行的转换时才可用。

6. 使用步骤

工作流一:从当前 Dragonfly 生成知识库并检索。

1. 在菜单中打开 Prototype Apps ▸ Obsidian Vault of Help Documents...。

2. 在 Help source 下拉框中确认帮助来源。默认会自动选中当前运行的 Dragonfly(“Current Dragonfly”);若需要转换另一套安装的帮助,点 Browse… 选择其 Help\Content 文件夹。

3. (可选)通过 Change… 修改 Build to 输出目录;不改则使用默认位置。

4. 点击 Convert & Build Vault。等待进度条走完(首次约 10–90 秒),状态栏会显示形如 “Built N notes, M images, K categories”(已生成 N 篇笔记、M 张图片、K 个分类)。

5. 若尚未安装 Obsidian,请先前往 obsidian.md 安装免费的 Obsidian 应用。

6. 点击 Open in Obsidian。首次打开时在 Obsidian 中点击 “Trust author and enable plugins” 以加载检索插件。

7. 在知识库中点击左侧的放大镜功能区图标(或在命令面板中运行 “Dragonfly Help Search”),输入您的问题,打开排名最靠前的结果。

工作流二:升级 Dragonfly 后重新生成。

1. 升级 Dragonfly 到新版本后,重新打开插件面板。

2. 确认 Help source 指向新版本(“Current Dragonfly” 会自动指向当前运行的版本)。

3. 点击 Convert & Build Vault 重新构建。重建会更新 Help、_attachments、_MOC、Home.md 等生成内容,但保留 `.obsidian` 目录(即您在 Obsidian 中的布局、主题与已装插件不会被覆盖)。

工作流三:Open in Obsidian 无反应时。

1. 点击 Open vault folder 打开知识库文件夹。

2. 在 Obsidian 中选择 “Open folder as vault”,把该文件夹拖入或选中即可。

7. 参数说明

面板对用户暴露的可配置项很少(核心就是一键转换),主要参数如下表。BM25 检索参数为插件内部固定值,列出供参考。

8. 输出结果

本插件不在 Dragonfly 中生成 Channel / ROI / MultiROI / Mesh 等对象,而是在磁盘上生成一个完整的 Obsidian 知识库文件夹。其结构如下:

• vault/Help/<分类>/<主题>.md —— 每个帮助主题一篇笔记,目录结构镜像原始 Content 树;含 YAML 前言(title / category / tags / source_rel_html / aliases)、一级标题 # 标题、干净的 Markdown 正文、真实的 Markdown 表格、由 MadCap 注意框转成的 Obsidian callout、由下拉块转成的小标题,以及解析为 [[双向链接]] 的内部链接。
• vault/_attachments/… —— 每张被引用的图片,按内容路径哈希复制(同名图片不会互相覆盖),笔记以相对路径引用。
• vault/Home.md —— 总览页(Map-of-Content),列出并链接所有分类。
• vault/_MOC/<分类>.md —— 每个分类一个索引页,以双向链接组织该分类下的笔记。
• vault/.obsidian/ —— Obsidian 配置(app / core-plugins / community-plugins / appearance)以及内置的 Dragonfly Help Search 检索插件(默认启用)。
• vault/_conversion_reports/ —— 转换摘要(conversion_summary.json,含笔记数、图片数、分类数、失败页列表等)。

如何查看。用 Obsidian 打开该知识库文件夹即可浏览:从 Home.md 进入各分类,或用左侧文件树浏览 Help 目录;点击放大镜功能区图标运行离线检索。也可以用任意 Markdown 编辑器或文本编辑器直接查看这些 .md 文件。

9. 常见问题与故障排除

问:菜单里找不到 “Obsidian Vault of Help Documents...” 怎么办?

答:菜单只在 Dragonfly 启动时扫描。请确认已在安装器或 Menu Item Manager 中勾选本插件,并完全退出后重启 Dragonfly。本插件在安装包中默认未勾选,首次安装需手动勾选。

问:面板提示 “No Dragonfly help detected” / 下拉框里没有帮助来源?

答:说明自动检测没有在常见位置找到 Help\Content。点击 Browse…,手动选择您 Dragonfly 安装目录下的 Help\Content 文件夹即可。您也可以事先设置环境变量 DF_HELP_CONTENT 指向该目录。

问:点击 “Open in Obsidian” 没有任何反应?

答:通常是尚未安装 Obsidian,或系统未注册 obsidian:// 协议。请先从 obsidian.md 安装 Obsidian;若仍无效,改用 Open vault folder 打开文件夹,再拖到 Obsidian 的 “Open folder as vault” 上。

问:在 Obsidian 里打开了知识库,但检索(放大镜)不工作?

答:首次打开时如果没有点击 “Trust author and enable plugins”,内置检索插件不会加载。请在 Obsidian 的设置中信任该文件夹并启用社区插件,或重新打开知识库并在提示时选择信任。

问:升级 Dragonfly 后重新生成,会不会把我在 Obsidian 里的布局、主题和其它插件都清掉?

答:不会。重建只更新生成内容(Help、_attachments、_MOC、Home.md),而保留整个 `.obsidian` 目录,因此您的工作区布局、主题与已装插件都会原样保留。

问:状态栏显示 “Build failed”,该怎么排查?

答:最常见原因是所选来源不含 .htm 帮助主题(会提示 “No .htm help topics under …”)。请确认选的是 Help\Content 目录而不是其上级目录。状态栏会显示错误的最后一行以便定位。

10. 注意事项与已知限制

• 生成的知识库内容取决于您所转换的 Dragonfly 版本;升级 Dragonfly 后建议重新生成以保持同步。
• 浏览知识库需要免费的 Obsidian 应用;插件本身不附带 Obsidian。
• 内置检索是基于关键词的 BM25 检索(检索最相关段落),它不是生成式问答——不会替您撰写答案,而是把最相关的帮助原文排序呈现。
• 含合并单元格(colspan/rowspan)或嵌套表格的复杂表格无法用 Markdown 表格表示,会保留为原始 HTML(Obsidian 可正常渲染),其中图片路径已改写为复制后的 _attachments 路径。
• MadCap 中条件化为其它产品变体(如 2D 专用内容)的片段以 HTML 注释形式存在,转换时会被跳过,因此知识库只保留 3D World 相关内容。
• 所有文件均写入当前用户目录(%LOCALAPPDATA%),无需管理员权限;每次修改插件勾选后需重启一次 Dragonfly。

11. 参考资料

• Obsidian 官方网站(免费下载):https://obsidian.md
• Dragonfly 帮助文档:Dragonfly 安装目录下的 Help\Content(本插件的转换来源)。
• BM25 排序算法:一种经典的信息检索加权算法,用于对文档与查询的相关度打分(检索插件的 K1=1.5、B=0.75)。
• lxml:Python 的 HTML/XML 解析库(Dragonfly 自带 Python 已包含),本插件用它完成 HTML→Markdown 解析。

Part II English Manual

Contents

1. Overview

2. Use Cases

3. Installation and Enabling

4. Runtime Environment and First-Run Setup

5. Interface Reference

6. Step-by-Step Usage

7. Parameters

8. Outputs

9. FAQ and Troubleshooting

10. Notes and Known Limitations

11. References

1. Overview

Obsidian Vault of Help Documents (menu title Obsidian Vault of Help Documents...) is a Dragonfly 3D World plugin. With one click it converts the Dragonfly help documentation already installed on your machine into an [Obsidian](https://obsidian.md)-friendly local knowledge base (a *vault*) and opens it. The generated vault also ships an offline retrieval plugin: you ask a question in plain language and it ranks the most relevant help passages with the BM25 algorithm — no internet, no API key, and no model download at any point.

The content it reads is Dragonfly's own help — the MadCap Flare HTML topics under <DragonflyInstall>\Help\Content in your Dragonfly install folder. The conversion performs the full HTML → Markdown transformation automatically: each help topic becomes a note with YAML frontmatter (title / category / tags / source / aliases); internal hyperlinks become [[wikilinks]]; tables become Markdown tables; MadCap note / tip / warning boxes become Obsidian callouts; collapsible dropdowns become sub-headings; and illustrations are copied into an _attachments folder (content-hashed) with their relative links preserved. The plugin then generates navigation (a Home.md overview and one _MOC index per category), writes the .obsidian config, and installs the bundled search plugin.

Underlying engine and algorithm. HTML parsing uses lxml (already bundled with Dragonfly's own Python), so the entire conversion runs on a background thread inside Dragonfly's own Python — no virtual environment (venv), no external program, and no internet. The bundled retrieval plugin is a plain CommonJS Obsidian community plugin (Dragonfly Help Search). When the vault loads, it builds an in-memory BM25 index (parameters K1=1.5, B=0.75, with title and category boosted 3×), tokenizes each note's body, and ranks notes by relevance to your query. This is "RAG without a model" — only the *retrieval* half, done locally and instantly.

Licensing notes. The help content comes from your own Dragonfly install and is not shipped with the plugin; the conversion engines (lxml and the Python standard library) are permissively licensed. The bundled search plugin is this project's own plain JavaScript code and requires no build step.

Why build on demand instead of shipping a ready-made vault? A pre-built vault can be well over a hundred MB, yet its content already exists in the Dragonfly help on your machine. Rebuilding locally means the install package is only a few hundred KB (code only); the generated vault always matches your installed Dragonfly version (2025.1, 2027.1, …); and you can rebuild anytime after a Dragonfly update.

2. Use Cases

This plugin suits any situation where you want to browse and search the Dragonfly help like a local wiki:

• Find descriptions fast: full-text searching the vault is quicker than paging through the help browser to locate a tool or workflow.
• Plug into Obsidian's backlinks and graph view: cross-references between help topics become [[wikilinks]], so Obsidian's graph shows how topics relate.
• Local RAG corpus: treat the vault as an offline retrieval corpus and ask plain-language questions such as "how do I segment cells with Cellpose" — the bundled search plugin returns the most relevant help passages.
• Offline, portable, distributable structure: because the content comes from your own Dragonfly install, the plugin ships no hundreds-of-MB payload; the generated vault is an ordinary folder you can copy or back up.

3. Installation and Enabling

This plugin ships with the Prototype Apps Full Package. Install it as follows:

1. Unzip the package to any short folder (e.g. C:\PL\) to avoid Windows' 260-character path limit on deep paths.

2. Double-click `Install_FullPackage.bat`.

3. In the dialog, pick the core install mode (Fresh or Compatible) and tick `Obsidian Vault of Help Documents...` in the plugin list.

4. Click Install and wait for the console to finish.

5. Fully quit and restart Dragonfly (menus are scanned only at startup).

This plugin is unticked by default in the installer (default state: light menu items on, all plugins off). Be sure to tick it during install, or enable it afterward as described below.

After the restart the plugin appears under Prototype Apps ▸ Obsidian Vault of Help Documents... (grouped under the "Help & Documentation" section, sorted after the data-processing tools).

Changing your choices later. The easiest way is inside Dragonfly: open Developer ▸ Prototype Labs... ▸ Menu Item Manager; the "Prototype Apps (Full Package)" list at the bottom has a checkbox per app — tick = deploy, untick = remove the menu entry — then restart Dragonfly to apply. Disabling never deletes any generated content, and re-enabling is instant. You can also re-run the installer anytime (it remembers your previous choices as the defaults).

Uninstall. Double-click `Uninstall_FullPackage.bat` to remove all Full-Package menu items and plugins; it does not delete any vault folder you generated.

4. Runtime Environment and First-Run Setup

This is an in-process plugin that runs on Dragonfly's own Python. Unlike many heavy plugins:

• There is no "Setup Environment" step: no virtual environment (venv) to build and nothing to download on first use. The required lxml is already bundled with Dragonfly's Python.
• No GPU is needed: both conversion and retrieval are pure-CPU, purely local operations.
• No internet is needed: the whole conversion runs offline, and search indexes locally too.
• No WSL or external compute software is required.

What to do on first use. Open the panel and simply click Convert & Build Vault. The first conversion takes about 10–90 seconds (depending on the size of your help documentation); the progress bar shows "converting help documents → assembling the vault". By default the vault is written to:

%LOCALAPPDATA%\DragonflyPrototypeLabs\ObsidianHelpVault\vault

External software dependency: Obsidian. The conversion itself needs no external program, but to open and browse the generated vault you need the free Obsidian app (obsidian.md). If the panel does not detect Obsidian, the status line prompts you to install it from obsidian.md.

The first time you open the vault in Obsidian, Obsidian asks whether to trust the folder. Click "Trust author and enable plugins" so the bundled Dragonfly Help Search retrieval plugin loads.

Fallback if it fails. If clicking Open in Obsidian does nothing (usually because Obsidian is not installed or the obsidian:// protocol is not registered), use Open vault folder instead, then drag that folder onto Obsidian's "Open folder as vault".

5. Interface Reference

The panel is a dockable (floating by default) PyQt6 window titled "Convert Dragonfly Help Documents to an Obsidian Vault". Top to bottom, the controls are:

• Description text (top): a short note on what the plugin does — build a local vault from your machine's Dragonfly help, with offline BM25 search.
• Help source dropdown: lists the Dragonfly Help\Content directories detected automatically. Detection order: the DF_HELP_CONTENT environment variable (if set) → the currently running Dragonfly's own help (labelled "Current Dragonfly") → other Dragonfly installs found in common locations. If nothing is found it shows "(no Dragonfly help found — use Browse…)".
• Browse… button: manually select a Dragonfly install's Help\Content folder (it is added to the top of the dropdown and selected).
• Build to field: the output directory for the vault, pre-filled with %LOCALAPPDATA%\DragonflyPrototypeLabs\ObsidianHelpVault\vault.
• Change… button: choose a different output directory; if the chosen folder is not named vault, the plugin appends a vault subfolder automatically.
• Convert & Build Vault button: the core action that starts the background conversion. It is disabled when no help source is available.
• Progress bar: shown only during conversion, range 0–100.
• Status line: a single line reporting the current state, progress messages, completion statistics, or errors (shown in red on error).
• Divider: the lower half of the panel holds the open actions.
• Open in Obsidian button: asks Obsidian to open the vault via the obsidian://open protocol.
• Open vault folder button: opens the vault's folder in the file explorer.
• Copy path button: copies the vault path to the clipboard.
• Bottom help text: a three-step reminder (build → install and open in Obsidian → search with the magnifier).

The three "open" buttons stay disabled until a vault exists (or the current build succeeds) and no conversion is running.

6. Step-by-Step Usage

Workflow 1: build a vault from the current Dragonfly and search it.

1. Open Prototype Apps ▸ Obsidian Vault of Help Documents... from the menu.

2. Confirm the help source in the Help source dropdown. It defaults to the currently running Dragonfly ("Current Dragonfly"); to convert a different install's help, click Browse… and select its Help\Content folder.

3. (Optional) Change the Build to output directory via Change…; leave it to use the default location.

4. Click Convert & Build Vault. Wait for the progress bar to finish (about 10–90 s the first time); the status line then shows something like "Built N notes, M images, K categories".

5. If Obsidian is not installed yet, install the free Obsidian app from obsidian.md first.

6. Click Open in Obsidian. The first time, click "Trust author and enable plugins" in Obsidian to load the search plugin.

7. In the vault, click the magnifier ribbon icon on the left (or run "Dragonfly Help Search" from the command palette), type your question, and open the top-ranked result.

Workflow 2: rebuild after a Dragonfly upgrade.

1. After upgrading Dragonfly to a new version, reopen the plugin panel.

2. Confirm the Help source points at the new version ("Current Dragonfly" automatically points at the running version).

3. Click Convert & Build Vault to rebuild. The rebuild refreshes the generated content (Help, _attachments, _MOC, Home.md) but preserves the `.obsidian` folder — your Obsidian layout, theme, and installed plugins are not overwritten.

Workflow 3: when Open in Obsidian does nothing.

1. Click Open vault folder to open the vault's folder.

2. In Obsidian choose "Open folder as vault" and select that folder.

7. Parameters

The panel exposes very few settings (the core action is one-click conversion). The main parameters are below. The BM25 retrieval parameters are fixed internal values, listed for reference.

8. Outputs

This plugin does not create Dragonfly objects such as Channels, ROIs, MultiROIs, or Meshes. Instead it produces a complete Obsidian vault folder on disk, structured as follows:

• vault/Help/<Category>/<Doc>.md — one note per help topic, mirroring the original Content tree; with YAML frontmatter (title / category / tags / source_rel_html / aliases), an # H1, a clean Markdown body, real Markdown tables, Obsidian callouts converted from MadCap notes, sub-headings converted from dropdowns, and internal links resolved to [[wikilinks]].
• vault/_attachments/… — every referenced image, copied with a content-path hash so same-named images never collide; notes link them by relative path.
• vault/Home.md — a Map-of-Content overview that lists and links every category.
• vault/_MOC/<Category>.md — one index note per category, organizing its notes with wikilinks.
• vault/.obsidian/ — the Obsidian config (app / core-plugins / community-plugins / appearance) and the bundled Dragonfly Help Search plugin (enabled by default).
• vault/_conversion_reports/ — a conversion summary (conversion_summary.json with note/image/category counts and a list of any failed pages).

How to view. Open the vault folder in Obsidian to browse it: start from Home.md into each category, or use the left-hand file tree to browse the Help folder; click the magnifier ribbon icon to run the offline search. You can also open any of the .md files directly in any Markdown or text editor.

9. FAQ and Troubleshooting

Q: The "Obsidian Vault of Help Documents..." menu item isn't there.

A: Menus are scanned only at Dragonfly startup. Make sure the plugin is ticked in the installer or Menu Item Manager, and fully quit and restart Dragonfly. The plugin is unticked by default, so it must be ticked on a first install.

Q: The panel says "No Dragonfly help detected" / the dropdown has no source.

A: Auto-detection did not find a Help\Content folder in the common locations. Click Browse… and pick the Help\Content folder inside your Dragonfly install. You can also set the DF_HELP_CONTENT environment variable to point at it beforehand.

Q: Clicking "Open in Obsidian" does nothing.

A: Usually Obsidian isn't installed, or the obsidian:// protocol isn't registered. Install Obsidian from obsidian.md first; if it still doesn't open, use Open vault folder and drag that folder onto Obsidian's "Open folder as vault".

Q: The vault opened in Obsidian, but search (the magnifier) doesn't work.

A: If you did not click "Trust author and enable plugins" on first open, the bundled search plugin never loaded. Trust the folder and enable community plugins in Obsidian's settings, or reopen the vault and choose to trust it when prompted.

Q: If I rebuild after a Dragonfly upgrade, will it wipe my Obsidian layout, theme, and other plugins?

A: No. A rebuild only refreshes the generated content (Help, _attachments, _MOC, Home.md) and preserves the entire `.obsidian` folder, so your workspace layout, theme, and installed plugins are kept as-is.

Q: The status line says "Build failed" — how do I diagnose it?

A: The most common cause is that the selected source contains no .htm help topics (you'll see "No .htm help topics under …"). Make sure you selected the Help\Content folder itself, not its parent. The status line shows the last line of the error to help pinpoint it.

10. Notes and Known Limitations

• The vault's content depends on the Dragonfly version you convert; rebuild after a Dragonfly upgrade to keep it in sync.
• Browsing the vault requires the free Obsidian app; the plugin does not bundle Obsidian.
• The bundled search is keyword-based BM25 retrieval (it retrieves the most relevant passages) — it is not generative Q&A; it does not write an answer for you, it ranks the most relevant original help text.
• Complex tables with merged cells (colspan/rowspan) or nested tables cannot be expressed as Markdown grids and are kept as raw HTML (Obsidian renders them fine), with image paths rewritten to the copied _attachments paths.
• MadCap fragments conditioned to other product variants (e.g. 2D-only content) exist as HTML comments and are skipped during conversion, so the vault keeps only the 3D World content.
• Everything is written under the current user's directory (%LOCALAPPDATA%), so no admin rights are needed; each change to the plugin's tick state needs one Dragonfly restart.

11. References

• Obsidian official website (free download): https://obsidian.md
• Dragonfly help documentation: the Help\Content folder inside your Dragonfly install (the conversion source for this plugin).
• BM25 ranking: a classic information-retrieval weighting algorithm that scores document relevance to a query (the search plugin uses K1=1.5, B=0.75).
• lxml: Python's HTML/XML parsing library (bundled with Dragonfly's own Python); the plugin uses it for the HTML→Markdown parsing.