如何自定义Docfx的///标签并在生成内容中渲染额外信息？

要实现自定义///标签并将其信息注入元数据.yml，核心是扩展Docfx的代码注释提取阶段，以下是具体步骤：

1. 实现自定义标签处理器 #

Docfx基于Roslyn分析代码注释，你需要创建自定义TagProcessor来识别EcsComponent标签并提取信息：

using Docfx.Common;
using Docfx.MarkdigEngine;
using Markdig.Syntax.Inlines;

public class EcsComponentTagProcessor : TagProcessor
{
    public override string TagName => "EcsComponent";

    public override void Process(TagProcessingContext context)
    {
        // 提取标签内的内容（比如外部链接地址）
        var linkUrl = context.Inline.FirstChild.ToString();
        
        // 将信息存入当前文档的元数据字典
        if (!context.Metadata.ContainsKey("EcsComponentLink"))
        {
            context.Metadata["EcsComponentLink"] = linkUrl;
        }
    }
}

2. 注册处理器到Docfx插件 #

创建插件类，在初始化时将自定义处理器注册到Markdown服务：

using Docfx.Plugins;
using Docfx.MarkdigEngine;

[Export(nameof(IHostService), typeof(IHostService))]
public class CustomDocfxPlugin : IHostService
{
    public void Initialize(IHostService host)
    {
        var markdownService = host.GetService<IMarkdownService>();
        if (markdownService != null)
        {
            markdownService.TagProcessors.Add(new EcsComponentTagProcessor());
        }
    }
}

3. 确保元数据写入.yml文件 #

上述代码中存入的EcsComponentLink会被Docfx自动写入目标类对应的.yml文件，最终你会看到类似字段：

...
EcsComponentLink: "https://example.com/ecs/component/xxx"
...

4. 在渲染阶段使用元数据 #

在Docfx模板文件（如class.tmpl）中，通过元数据字段渲染额外信息：

{{#if EcsComponentLink}}
<div class="ecs-component-info">
    <a href="{{EcsComponentLink}}" target="_blank">查看EcsComponent详情</a>
</div>
{{/if}}

注意事项 #

• 插件编译为.dll后，需在docfx.json的plugins字段中引用：

  "plugins": [
    "path/to/YourCustomPlugin.dll"
  ]
  

• 代码注释需遵循正确格式：

  /// <summary>玩家组件</summary>
  /// <EcsComponent>https://example.com/ecs/player</EcsComponent>
  public class PlayerComponent { ... }
  

内容的提问来源于stack exchange，提问作者Антон Гааг