Oxygen XML Author 是面向 DITA 的专业编辑器，非完整开发环境，需集成 DITA-OT 实现转换；配置须指定正确路径、验证可执行权限并启用插件；DITA Map 必须通过模板创建，主题路径须相对且格式合法；自定义元素需注册 schema 并重启生效。

Oxygen XML Author 本身不是 DITA 开发“环境”，而是面向结构化文档（尤其是 DITA）的专业编辑器；它不编译、不构建、不部署，但能高效编写、验证、预览和协作 DITA 内容。真正完成 DITA 开发闭环，必须配合 DITA-OT（DITA Open Toolkit）和合理项目结构。

怎么配置 DITA-OT 集成到 Oxygen

Oxygen 依赖外部 DITA-OT 实现转换（PDF/HTML5/EPUB 等），不自带完整工具链。配置错误是新手最常卡住的环节。

• 下载匹配版本的 DITA-OT（推荐 dita-ot-4.4 或 dita-ot-4.3，避免用最新 beta 版——Oxygen 25.1 对 dita-ot-4.5 支持尚不稳定）
• 在 Oxygen → Options → Preferences → DITA → DITA Open Toolkit 中指定 DITA-OT 根目录（即含 bin/、plugins/ 的文件夹）
• 确认 bin/dita（Linux/macOS）或 bin/dita.bat（Windows）可执行；若提示 “DITA-OT not found”，大概率是路径末尾多了斜杠，或权限不足（macOS/Linux 需 chmod +x bin/dita）
• Oxygen 启动时会在底部状态栏显示 DITA-OT: 4.4 (valid)，否则说明未生效

如何创建合法的 DITA Map 并关联主题

DITA 开发从 .ditamap 文件开始，不是单个 .dita。Oxygen 不会自动帮你补全 或 属性，写错就无法解析导航。

• 用 File → New → Framework Templates → DITA → DITA Map 创建，别手动建空 XML 文件再改后缀
• 中的路径必须相对于 ditamap 文件位置，不是相对于 project root；Oxygen 不做路径映射
• 确保引用的 install_server.dita 文件存在且根元素为 （或 /），否则 Oxygen 校验报 Invalid topic type
• 不要在 上乱加 format="html"——DITA-OT 转换时会忽略，只认 format="dita"（默认）或 format="markdown"（需插件）

为什么按 F9 生成 PDF 却只弹出空白浏览器窗口

这是 Oxygen 中最典型的“假失败”：表面没报错，实际转换中途静默退出，原因几乎全是 DITA-OT 配置或资源路径问题。

• F9 默认触发 PDF - based on DITA-OT 转换场景，但该场景依赖 org.dita.pdf2 插件是否启用；检查 DITA-OT/plugins/ 下是否存在该文件夹，且 plugin.xml 中未被注释
• 如果项目用了自定义 CSS（如 custom.css），必须在 pdf2/custom.xsl 或 cfg/fo/attrs/custom.xsl 中显式引用，Oxygen 不自动注入
• Windows 用户常见坑：DITA-OT 路径含中文或空格（如 C:\Users\张

  

  三\tools\dita-ot），会导致 Java 进程启动失败，日志里只显示 ERROR: Failed to run transformation，无具体原因
• 查看真实错误：打开 Transformation Scenarios → Edit → Output tab → Check "Show output in console"，重跑 F9，错误堆栈会直接输出在底部控制台

Building file:/C:/work/myproject/map.ditamap
[error] Failed to resolve URI 'images/server_arch.png': java.io.FileNotFoundException: C:\work\myproject\images\server_arch.png (The system cannot find the file specified)
[error] Transformation failed: java.lang.NullPointerException

怎么让 Oxygen 正确识别自定义 DITA 元素或属性

一旦引入私有 domain（如 ）或扩展属性（如 audience="admin"），Oxygen 默认不校验也不高亮，需要手动注册 schema 或 grammar。

• 把自定义 XSD 或 RNG 文件（如 my-domain.mod）放到项目 catalog.xml 可识别的路径下
• 在 Oxygen → Options → Preferences → XML / XML Catalog 中添加该 catalog.xml，确保其包含类似条目：
• 在 ditamap 或 dita 文件顶部声明命名空间（RNG）或 DOCTYPE（DTD），例如：%my-domain;]>
• 重启 Oxygen —— schema 注册不会热加载，不重启无效

DITA 开发中真正的复杂点不在 Oxygen 操作，而在于 DITA-OT 插件行为不可见、domain 扩展缺乏 IDE 级支持、以及 ditamap 导航逻辑必须手写正确。Oxygen 做得最好的是实时验证和所见略同的预览，但别指望它替你理解 chunk 属性怎么影响 HTML 分页，或者 keyref 在多层 map 嵌套中如何解析。