使用Oxygen XML Editor 20.0转换轻量级DITA Markdown至HTML遇阻求助

二、正确转换MDITA到HTML的两种方式

方式1：在Oxygen XML Editor 20.0里操作

1. 配置LwDITA文档关联
   • 打开Oxygen，点击顶部菜单「选项 > 偏好设置 > 文档类型关联」。
   • 点击「新建」，选择「LwDITA」作为基础框架，确认勾选MDITA支持选项。
   • 右键你的index.md文件，选择「属性 > 文档类型」，关联到刚才配置的LwDITA框架。
2. 制作符合规范的MDITA Ditamap
   • 新建一个ditamap文件，引用MD文件时必须加上format="markdown"属性，示例代码如下：

     <map>
       <title>TRS-80 Expansion Module Guide</title>
       <topicref href="index.md" format="markdown"/>
       <!-- 其他MD主题引用都要添加format属性 -->
     </map>
     

   • 同样将这个ditamap的文档类型设为「LwDITA Map」。
3. 执行转换
   • 打开ditamap，点击工具栏的「配置转换场景」。
   • 选择「LwDITA HTML5」场景（如果没有该选项，说明Oxygen自带的DITA-OT未安装LwDITA插件，可通过「工具 > DITA-OT > 安装插件」搜索org.lwdita完成安装）。
   • 点击运行即可生成正确的HTML输出。

方式2：用DITA-OT 3.0.3命令行操作（更稳定）

1. 确认LwDITA插件已安装
   • 打开终端，进入DITA-OT安装目录，运行：

     bin/dita --list-plugins
     

   • 如果看不到org.lwdita插件，执行安装命令：

     bin/dita install org.lwdita
     

2. 转换单MDITA文件
   • 直接运行以下命令（替换为你的实际文件路径）：

     bin/dita --input=/path/to/index.md --format=lwdita-html5
     

3. 转换MDITA Ditamap
   • 确保ditamap已正确添加format="markdown"属性，然后运行：

     bin/dita --input=/path/to/your-map.ditamap --format=lwdita-html5
     

三、转换为PDF的方法

不管用Oxygen还是命令行，都可以使用LwDITA专属的PDF转换场景：

• 命令行方式：

  bin/dita --input=/path/to/your-map.ditamap --format=lwdita-pdf
  

• Oxygen图形界面：在转换场景列表中选择「LwDITA PDF」即可；如果需要自定义PDF样式，可以修改LwDITA的PDF模板文件。

额外小贴士

• DITA-OT 3.0.3的LwDITA插件版本较老，建议升级到DITA-OT 4.x版本，对MDITA的Markdown语法支持更完善，兼容性也更好。
• 你的MD文件必须符合MDITA规范，例如键引用要使用{keyref="your-key"}这种DITA扩展语法，不能用普通Markdown的链接格式，否则转换时会触发报错。

内容的提问来源于stack exchange，提问作者Lily