Option to specify default non-categorized/grouped reflection name

[sergeiivankov]

Search Terms

none, default category, default group, top-level navigation

Problem

I try to make documentation navigation structure like next (with most common usage entities in top level navigation, without hidden its behind category/group dropdown element).

• Entity1
• Entity2
• ...
• Advanced category
  -- Advanced category Entity 1
  -- Advanced category Entity 2
  -- ...
• Internal category
  -- Internal category Entity 1
  -- Internal category Entity 2
  -- ...

I found code

typedoc/src/lib/output/themes/default/DefaultTheme.tsx

Line 266 in 3a3976d

const none = reflection.find((x) => x.title.toLocaleLowerCase() === "none");

, so I named category for top level navigation entities None to get the behavior I want.

But in modules documentation page shows category name None, it's not very nice, I would like to be able to change this default name.

I do this with categoriest, but I think this works similarly with groups too.

Suggested Solution

Add option for TypeDoc to change default name for non-collectibles reflections.

[Gerrit0]

Would it be better for the modules page to be rendered like the navigation, leaving those elements outside of a group/category entirely?

[sergeiivankov]

I think this is a good solution. On the other hand, in the current version there is an option to specify a description of the base category (entity without a category), in your proposal, if I understand correctly, there will be no such option.

[Gerrit0]

The category description should be unnecessary, the top of the module page renders the comment for the module, which seems like it ought to be sufficient to me...

[pjeby]

Possibly related: there doesn't seem to be a way to make a module page not have groups or categories -- @hideGroups only affects the navigation tree, not the page rendering. Is that intentional? Right now if you want your module contents to be flat you have to put everything in the same category or group, which then has the issue of either including a spurious heading in both the page and the nav tree, or needing the spurious page heading to be called "None".

[Gerrit0]

Yes, the navigation and module structure is completely separate as I simply hadn't considered if module pages should care about those tags. I'm leaning towards TypeDoc should use the same logic for both for consistency.

[Gerrit0]

Upon further reflection, I'm backtracking here a bit... Trying to make the navigation and page structure follow the same rules is nice at first, but runs into problems because they are truly different things. The navigation has customization options that it would be very weird to have the module page follow, and @showGroups / @hideGroups were truly meant only for the navigation, not to also affect the page contents.

in both the page and the nav tree

Only if you have turned on the navigation.includeGroups option, which is off by default.

---

I am going to introduce a @disableGroups tag which completely disables the grouping mechanism for a given parent, which will result in both the navigation and the page not including group sections. Including this in @hideGroups would be a breaking change, which I don't want to do as I don't want to start a beta branch so close to the 0.28 release.

[pjeby]

Hm. I just tried the dev branch, and @disableGroups works great, but @category none isn't working on reflections that are members of a class; should it?

[pjeby]

Also, @disableGroups on a class whose members aren't categorized results in the members being listed twice on the on-page nav, as both top-level items and items under a "none" category:

[Gerrit0]

@category none isn't working on reflections that are members of a class; should it?

This and the double navigation bug were both caused by forgetting a return facepalm

[pjeby]

Hey, we've all been there. 😁 Anyway, it works great now!