如何修复DocFX示例代码的语法高亮问题

问题原因 #

DocFX对API签名的<code>标签有内置语法高亮处理，会自动添加class="lang-csharp hljs"属性，但对<example>标签内的<code>不会默认添加该属性，导致高亮失效。

解决办法 #

1. 手动给<code>标签指定语言属性 #

在XML文档注释的<code>标签里添加language="csharp"属性，示例如下：

<example>
  <code language="csharp">
    int Calculate(int a, int b)
    {
        return a + b;
    }
  </code>
</example>

DocFX生成HTML时会自动给这个<code>标签加上lang-csharp hljs类，语法高亮即可正常显示。

2. 修改DocFX模板统一处理 #

如果不想逐个修改注释，可以自定义DocFX模板：

• 找到本地DocFX默认模板的存放目录（一般是templates\default）
• 定位到处理代码块的模板文件（比如涉及<example>渲染的liquid模板）
• 修改模板逻辑，给所有<example>内的<code>标签默认添加lang-csharp hljs类
• 重新执行DocFX构建命令，让模板生效

3. 批量脚本修改已有注释 #

如果已有大量未添加属性的示例代码，可以用脚本批量处理：

• 编写PowerShell或Python脚本，遍历所有包含XML注释的代码文件
• 自动给<example>标签内的<code>节点添加language="csharp"属性
• 执行脚本完成批量修改后，再重新构建文档

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