如何在DITA-OT 3.0.4的HTML5转换中覆盖默认CSS？
我正在使用DITA-OT 3.0.4，尝试通过以下命令将Markdown文件（通过DITA映射）转换为HTML5：
dita --input="note.ditamap" --output="out" --format=html5 --args.css=style.css --args.cssroot=metadata --args.copycss=yes --args.csspath=css
我的目录结构如下：
├── note.ditamap └── metadata ├── note.properties └── style.css # 自定义CSS文件
转换成功完成，但输出的HTML文件（如index.html）并未引入我的自定义CSS。我也尝试过使用属性文件启动转换，结果依旧：
dita --input="note.ditamap" --output="out" --format=html5 --propertyfile="metadata/note.properties"
note.properties的内容如下：
args.csspath = css args.copycss = YES args.css = style.css args.cssroot = metadata
我发现输出HTML引用的是默认CSS：${DITA_INSTALL_DIR}/dita-ot-3.0.4/plugins/org.dita.html5/css/commonltr.css，把自定义CSS追加到这个文件能实现效果，但这会影响所有其他项目，显然不是合理方案。我查阅了相关文档仍未找到解决方法，恳请大家提供建议。
解决方案建议
作为经常处理DITA-OT定制化的开发者，我给你几个排查和解决的方向：
先确认CSS文件是否被正确复制到输出目录
你设置了args.copycss=yes和args.csspath=css，转换完成后去out/css目录看看style.css是否存在。如果不存在，说明DITA-OT没找到你的源CSS文件，大概率是args.cssroot的路径问题——试试换成绝对路径（比如/Users/you/project/metadata或者C:\projects\your-project\metadata），避免相对路径解析的歧义。检查DITA映射的元数据配置
有时候默认模板不会自动关联自定义CSS，你可以在note.ditamap中显式添加CSS引用：<topicmeta> <navtitle>我的文档</navtitle> <link rel="stylesheet" href="css/style.css" type="text/css"/> </topicmeta>这样强制HTML输出引入你的自定义样式，绕过模板的默认逻辑。
验证属性文件的格式和优先级
确保note.properties中每个参数单独一行，没有多余的空格，编码为UTF-8无BOM。另外，如果你同时用命令行参数和属性文件，命令行参数会覆盖属性文件的配置——所以用属性文件的时候，命令行里别再写CSS相关参数了。启用 verbose 日志定位问题
在转换命令中添加--verbose参数，查看详细日志：dita --input="note.ditamap" --output="out" --format=html5 --propertyfile="metadata/note.properties" --verbose日志里会显示DITA-OT处理CSS的过程，比如有没有报错“找不到style.css”，或者复制文件时的路径错误，这能帮你快速定位根因。
尝试自定义HTML模板
如果默认模板的CSS引用逻辑有问题，你可以复制DITA-OT自带的HTML5模板（位于plugins/org.dita.html5/xsl/目录下），修改其中的CSS引用部分，确保它指向你的自定义CSS，然后用--args.hdf=your-custom-template.xsl参数指定使用这个模板。考虑升级DITA-OT版本
DITA-OT 3.0.4是比较老的版本了（发布于2018年），后续的3.x版本修复了不少CSS处理的bug。如果以上方法都无效，升级到3.x的最新稳定版（比如3.7.4）或者4.x版本，可能会直接解决这个问题。
内容的提问来源于stack exchange，提问作者tkhm
