leechristensen/ghidra_markdown_docs

# Ghidra 帮助文档转 Markdown 工具 将 Ghidra 的 HTML 帮助文档转换为 Markdown，并提供最大努力的交叉引用和导航。 凭直觉编写，可能有些地方存在问题，但整体效果相当不错！ ## 快速入门 将其指向已安装的 Ghidra： ``` uv sync uv run ghidra-help-to-markdown /path/to/ghidra ./docs ``` 或者指向源码树检出目录（适用于标记版本和开发构建）： ``` git clone --depth 1 --branch Ghidra_12.0.4_build https://github.com/NationalSecurityAgency/ghidra uv run ghidra-help-to-markdown ./ghidra ./docs --ghidra-install /path/to/installed/ghidra ``` 无论哪种方式，输出结果都会存放在 `./docs/Ghidra_/` —— 版本号 会从 `Ghidra/application.properties` 中读取并自动附加，以便 多个构建版本可以共存： ``` docs/ Ghidra_12.0.4_PUBLIC/ Ghidra_11.3_DEV/ ... ``` ## 模式 转换器会检测你指向的目录，并自动选择以下两种模式之一： - **已安装的 Ghidra (运行时模式)**：目录中包含 `ghidraRun`。 通过 [`pyghidra`](https://pypi.org/project/pyghidra/) 启动无头 Ghidra JVM 并直接从模块 jar 包中读取帮助信息。无需提取文件系统。 跨模块链接解析和图标查找通过 Ghidra 自身的 `GhidraHelpService` 和 `HelpBuildUtils` 进行 —— 与 Swing 帮助 查看器使用的代码相同。 - **源码树模式**：目录包含 `**/src/main/help/help/topics/`。 直接在磁盘上遍历帮助文件。向已构建/安装的 Ghidra 传入 `--ghidra-install `，以解析程序化图标引用 （`Icons.ADD_ICON`、`icon.bsim.connected`）；若不提供此参数，这些引用将回退 为文本占位符。 ## 选项 ``` --ghidra-install PATH Path to an installed/extracted Ghidra. Required for programmatic icon resolution. Optional in runtime mode (ghidra_root itself is used). --module NAME Convert only the named topic (e.g. DecompilePlugin). --no-images Skip image copying. --verbose, -v Show detailed progress. ``` ## 兼容性 | Ghidra | 运行时模式 | 源码树模式 | |---|---|---| | 12.0+ | ✅ | ✅ | | 11.0 – 11.4 | ❌ (PyPI pyghidra 要求 Ghidra 版本 ≥12.0) | ✅ (克隆源码标签，将 `--ghidra-install` 指向 12.x 安装目录以获取图标) | 已通过端到端测试的版本包括 11.0、11.3、12.0.4、12.1_DEV 和 12.2_DEV。 ## 项目结构 ``` src/ghidra_help_to_markdown/ main.py # Entry point, orchestrates the pipeline ghidra_session.py # Lazy pyghidra session (idempotent start, theme init) runtime_help.py # Reads merged help model from running Ghidra JVM toc_parser.py # Parses TOC_Source.xml into a TOC tree (source mode) html_converter.py # HTML to Markdown body conversion link_resolver.py # help/topics/... -> relative Markdown paths icon_resolver.py # Resolves icon refs via HelpBuildUtils + classpath generate_full_index.py # Expands index.md with each page's headers validator.py # Standalone link/anchor/render checker ``` ## 转换流水线 在运行时模式下： 1. **JVM 引导** —— 启动 pyghidra，初始化 `HeadlessThemeManager`，调用 `GhidraHelpService.install()` 以合并所有 `_HelpSet.hs`。 2. **TOC 遍历** —— 从 `getMasterHelpSet()` 遍历已合并的 TOC 树。 3. **主题枚举** —— 遍历每个已加载 HelpSet 的本地映射，获取完整的跨模块主题列表（在实际安装中约有 2700 个主题）。 4. **HTML 获取** —— 通过其 `jar:file:.../!/help/topics/...` URL 上的 `URL.openStream()` 读取每个主题的字节数据。 5. **HTML 转 Markdown** —— `html_converter.py` 负责处理标题、表格、 列表、代码块、定义列表（pandoc 风格）、提示框 (note/tip/warning)、键盘快捷键和可点击的图片。 6. **链接解析** —— 将 `help/topics/X/Y.htm#anchor` 重写为相对路径 `X/Y.md#slug`，并对锚点进行 slug 化处理以匹配 GFM 标题 slug。 7. **图标解析** —— 程序化引用（`Icons.X`、`icon.X`）和 jar 根目录图片（``）通过 `HelpBuildUtils.locateImageReference` 和 `ResourceManager.getResource` 进行处理， 提取的字节将被缓存并复制到 `docs/.../icons/`。 8. **图片提取** —— 将 `help/topics//images/*` 和 `help/shared/*` 从模块 jar 包中提取到相应的输出路径。 9. **外部文档** —— 转换 `WhatsNew`、`ChangeHistory`、`README_PDB`、 `InstallationGuide`（Ghidra 源码格式有所不同：11.x 版本为 HTML， 12.x 版本为 Markdown —— 两者均可处理）。 10. **索引 + 导航** —— 生成主 `index.md`、各模块的 `index.md`、 面包屑导航和上一页/下一页链接，以及包含所有 页面标题的 `index-full.md`。 在源码树模式下，步骤 1–4 替换为直接在文件系统上遍历 `**/src/main/help/help/topics/`；其余步骤完全相同。 ## 输出 ``` docs/Ghidra_/ index.md # Master TOC index-full.md # Full TOC expanded with every page's headers icons/ # Resolved icons (jar-extracted + theme-resolved) images/ # Logo + master-index images shared/ # Shared images (note.png, etc.) docs/ # External docs (WhatsNew, ChangeHistory, README_PDB) Misc/Tips.md # Tip-of-the-Day (generated from tips.txt) / index.md # Topic index *.md # Converted help pages images/ # Topic-specific images ``` ## 验证 ``` # 快速内置检查器（作为最后转换步骤自动运行） uv run ghidra-docs-validator ./docs/Ghidra_12.0.4_PUBLIC # 通过 mkdocs 进行渲染 + 链接/锚点检查。封装了 `mkdocs build --strict` # 并在出现任何警告时失败（锚点损坏、未知的 nav 文件、缺失的 # 片段）。在每次更改 converter 或编辑 doc 后运行此检查。 ./scripts/check_links.sh ``` 内置验证器可以捕获损坏的内部链接、格式错误的表格、 未闭合的粗体/反引号标记、缺失的图片文件，以及同行内 锚点+标题的渲染错误。`mkdocs build --strict` 还会根据目标文件中渲染的标题 slug 和任何 `` 标记，额外验证每个 `[文本](path.md#anchor)` 引用（通过 `mkdocs.yml` 中的 `validation:` 进行配置）。