docFX - Remove namespace prefix in API Reference TOC

Question

I am generating API reference from C# project. The project is part of big solution and has long name convention for assemblies and namespaces, so every namespace in project goes like [CompanyName].[System].[Area].[Module].[...] (e.g. MyBiz.CRM.Sales.Analytics.Persistence.Common and MyBiz.CRM.Sales.Analytics.Persistence.Sql). Since all namespaces in project start with MyBiz.CRM.Sales. and I generate reference for each system and area separately, I want to exclude MyBiz.CRM.Sales. in TOC on left side and only mention it in title/header.

Is it possible in docFX or I need to write custom server side post-build event script?

Thanks in advance

score 3 · Accepted Answer · answered Oct 22 '19 at 07:42

I also had the same problem and solved it by writing a template. The only thing it does is overriding the preTransform hook which you need to specify in a file named toc.extension.js. There I strip the long namespace prefix. As I have a TOC in several layers, I do that recursively. You can most probably hard-code it for the level you need. My code looks as follows:

exports.preTransform = function (model) {
  // replace recursively the root namespace by ""
  transformItem(model, 1);
  return model;

  function transformItem(item, level) {
    if (item.name) {
      item.name = item.name.replace("Some.Very.Long.Namespace.Prefix.", '');
    } else {
      item.name = null;
    }

    if (item.items && item.items.length > 0) {
      var length = item.items.length;
      for (var i = 0; i < length; i++) {
        transformItem(item.items[i], level + 1);
      };
    }
  }
}

Afterwards, I simply specify the own template in addition to the default template in docfx.json which causes the hook to be called. That works as follows:

"build": {
    "template": [
        "default",
        "/path/to/your/template/folder"
    ]
}

References: Docfx: How to create a custom template

score 0 · Answer 2 · answered Apr 19 '23 at 16:49

In DocFX 2.65, you can set the namespaceLayout property in the metadata section in docfx.json with the following properties:

flattened: Namespace node in TOC is a list.
nested: Namespace node in TOC is nested.

Reference: https://dotnet.github.io/docfx/docs/dotnet-api-docs.html#customization-options

docFX - Remove namespace prefix in API Reference TOC

2 Answers2