How to force grouping by @category even when none are defined?

[Jym77]

So, trying to convert a large codebase to Typedoc… 🎉

With default setup, the pages are organised by kinds: "Namespaces, Classes, …" (and seem to not respect kindSortOrder 🤔). This is not how I prefer to display them (for reasons, I can elaborate if needed).

If I add a @category Foo tag to some entries, then the page gets organised as "Foo, Other" categories (and kindSortOrder is respected within each category); if I add a @group Foo tag instead, then it gets organised as "Foo, Namespace, Classes, …" groups and kinds.

Now, the thing is that I prefer the way things are shown in the "category" case, even for the content of the "Other" default category, I think it makes more sense (for this codebase) to present stuff that way than separated by kind.
But it is not very realistic to add a category to all entries, or even to sufficiently many to trigger that mode on every page (given the size of my codebase… this may happen organically as time goes, but definitely not during initial setup).

So, is there an option to say "if no @group nor @category tags are present, treat that as 'everything is in the Other category' rather than defaulting to grouping by kinds"?

[Gerrit0]

and seem to not respect kindSortOrder

You want the groupOrder option, the kindSortOrder option defines the ordering of reflections within a group or category.

So, is there an option to say "if no @group nor @category tags are present, treat that as 'everything is in the Other category' rather than defaulting to grouping by kinds"?

There is not, that's a very specific configuration... However, it is not hard to write a custom plugin which does this and can even be inlined in your configuration file.

// CC0
import * as td from "typedoc";

/** @param {td.Application} app */
export function load(app) {
    app.converter.on(td.Converter.EVENT_RESOLVE, (_context, refl) => {
        if (!refl.isDeclaration()) return;

        // It probably only really makes sense to do this to modules, enumerations
        // look rather weird when all their members are under "Other"
        if (!refl.kindOf(td.ReflectionKind.ExportContainer)) return;

        const children = refl.childrenIncludingDocuments || [];
        if (!children.some(child => child.comment?.getTag("@group") || child.comment?.getTag("@category"))) {
            // The category plugin won't re-do work if reflections have already been categorized, so we can
            // just specify the categories here directly. You could also use groups here instead of categories.
            refl.categories = [
                new td.ReflectionCategory(app.options.getValue("defaultCategory")),
            ];
            refl.categories[0].children = [...children];

            // You might want to consider instead disabling grouping for this reflection,
            // categories will also do nothing since there are no @category comments.
            //   refl.comment ||= new td.Comment();
            //   refl.comment.modifierTags.add("@disableGroups");
        }
    });
}

[Jym77]

Thanks. I think I understand the idea behind the plugin. I'll look into it deeper at the end of the month (when I can allocate time to work on that again…)

[Jym77]

Finally got time to get back to that 😅Thanks for the help getting me on the correct rails…
Turns out:

1. Your solution is skipping the top-level (since it categorizes children of Declaration, not Project) (easy fix).
2. Hacking refl.categories directly interferes with the sorting order (I assume the category plugins does that normally), so I went for just adding a new tag to the comment, and letting the rest of the pipeline do its magic, which in turns simplifies the logic of looking into the children.
3. Given that my use case is that I often have a namespace and a class with the same name (merged into the same ES object), I could use that name as the category name and that's pretty much what I really wanted 😁

My final(ish) plugin:

import * as TypeDoc from "typedoc";

/**
 * Add a Category to all declaration reflections, if they don't already have
 * one (nor a group). The category has the same name as the reflection.
 *
 * @param {TypeDoc.Application} application
 * */
export function load(application) {
  application.converter.on(
    TypeDoc.Converter.EVENT_RESOLVE,
    (_context, reflection) => {
      if (!reflection.isDeclaration()) {
        return;
      }

      if (
        reflection.kindOf([
          // Enum member make little sense when not grouped as Enum member.
          TypeDoc.ReflectionKind.EnumMember,
          // Seems to be something with type re-exported by the index?
          // Not clear why, but these get duplicated under a __type heading
          // if not ignored.
          TypeDoc.ReflectionKind.TypeLiteral,
        ])
      ) {
        return;
      }

      // Get the reflection's comment, adding an empty one if needed.
      const comment = (reflection.comment ??= new TypeDoc.Comment());

      // If the reflection has no group nor category, add one.
      if (!comment.getTag("@group") && !comment.getTag("@category")) {
        comment.blockTags.push(
          new TypeDoc.CommentTag("@category", [
            { kind: "text", text: reflection.name },
          ]),
        );
        // }
      }
    },
  );
}