DITA-OT 2.5.4 HTML5插件：args.hdr为何未在index.html中显示？

使用MadCap Ixia搭配DITA-OT 2.5.4发布HTML内容时，已通过args.hdr属性配置页面头部（header.xml），且该头部已成功显示在多数HTML文件中，但index.html始终无法加载头部。

相关配置与现象如下：

• 头部文件header.xml内容：

<div class="header">
  <p>My header</p>
</div>

• 构建脚本build_dita2html5.xsl中添加的属性：

<project xmlns:dita="http://dita-ot.sourceforge.net" name="dita2html5">
    <property name="dita.dir" location="%path-to-DITA-OT%"/>
    <property name="args.css" value="dita-ot-doc.css"/>
    <property name="args.cssroot" value="/opt/ixiasoft/outgen/data/dita-ot-2.5.4/plugins/com.dde.html5/css"/>
    <property name="args.copycss" value="yes"/>
    <property name="args.csspath" value="css"/>
    <property name="html5.nav-toc" value="full"/>
    <property name="args.html5.toc" value="Home"/>
    <property name="args.hdr" value="file:/opt/ixiasoft/outgen/data/dita-ot-2.5.4/plugins/com.dde.html5/extra_files/header.xml"/>
...
</project>

• 构建日志确认属性已识别：

[echo] args.hdr=file\:/opt/ixiasoft/outgen/data/dita-ot-2.5.4/plugins/com.dde.html5/extra_files/header.xml

• 正常HTML文件的头部渲染结果：

<!DOCTYPE html
  SYSTEM "about:legacy-compat">
<html lang="en-us">
    <head>
[etc...]
    </head>
    <body id="amx1736432783724">
        <header role="banner">
            <div class="header">
                <p>My header</p>
            </div>
        </header>
[etc...]

• index.html缺失头部的情况：

<!DOCTYPE html
  SYSTEM "about:legacy-compat">
<html lang="en-us">
   <head>
[etc...]
   </head>
   <body id="itg1736432564160">
<!-- Where is my header? -->    
      <h1 class="title topictitle1">My Title</h1>

原因 #

DITA-OT 2.5.4中，index.html由TOC（目录）转换生成，其渲染逻辑独立于普通主题页面，默认不会读取args.hdr配置的头部内容。

修复步骤 #

1. 定位TOC转换模板文件
   找到DITA-OT HTML5插件的TOC处理XSL文件，路径通常为：

   /opt/ixiasoft/outgen/data/dita-ot-2.5.4/plugins/org.dita.html5/xsl/toc.xsl
   

2. 修改模板插入头部内容
   在toc.xsl中找到生成<body>标签的核心模板（通常匹配*[contains(@class, 'map/map')]节点），添加读取并插入args.hdr内容的逻辑：

   <xsl:template match="*[contains(@class, 'map/map')]" mode="toc-html">
     <html>
       <!-- 保留原有head部分代码 -->
       <body>
         <!-- 新增头部插入逻辑 -->
         <xsl:if test="$args.hdr != ''">
           <header role="banner">
             <xsl:copy-of select="document($args.hdr)/*"/>
           </header>
         </xsl:if>
         <!-- 保留原有TOC内容渲染代码 -->
         <h1 class="title topictitle1"><xsl:value-of select="$args.html5.toc"/></h1>
         <!-- 其余原有代码 -->
       </body>
     </html>
   </xsl:template>
   

3. 重新构建发布
   保存修改后的toc.xsl，重新执行DITA-OT构建，index.html即可加载配置的头部内容。

备选方案（无侵入式扩展） #

若不想修改DITA-OT核心文件，可通过自定义插件实现：

• 创建自定义HTML5插件，在插件的XSL文件中重写TOC渲染模板，添加头部插入逻辑；
• 将自定义插件注册到DITA-OT，并确保其优先级高于默认的org.dita.html5插件。

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