fix(core): added support for@group none, @category none and @disableGroups

tgreyuk · tgreyuk · commit ef583ee29325 · 2025-04-09T17:01:48.000+01:00
diff --git a/.changeset/thick-poets-buy.md b/.changeset/thick-poets-buy.md
@@ -0,0 +1,5 @@
+---
+'typedoc-plugin-markdown': patch
+---
+
+- Added support for TypeDoc's v0.28.2 features `@group none`, `@category none` and `@disableGroups`.
diff --git a/docs/content/docs/options/display-options.mdx b/docs/content/docs/options/display-options.mdx
@@ -40,24 +40,6 @@ Options that are used to configure how the output is structured and displayed.
 }
 ```
 
-## hideGroupHeadings
-
-<Callout emoji="💡">
-  Excludes grouping by kind so all members are rendered at the same level.
-</Callout>
-
-> Accepts a boolean value. Defaults to `false`.
-
-By default members are grouped by kind (eg Classes, Functions etc).
-
-This creates a flat structure where all members are displayed at the same heading level.
-
-```json filename="typedoc.json"
-{
-  "hideGroupHeadings": false
-}
-```
-
 ## useCodeBlocks
 
 <Callout emoji="💡">Wraps signatures and declarations in code blocks.</Callout>
diff --git a/docs/content/docs/options/index.mdx b/docs/content/docs/options/index.mdx
@@ -32,7 +32,6 @@ Options that are used to configure how the output is structured and displayed.
 | [hidePageHeader](./options/display-options.mdx#hidepageheader)                       | Do not print page header.                                                 |
 | [hideBreadcrumbs](./options/display-options.mdx#hidebreadcrumbs)                     | Do not print breadcrumbs.                                                 |
 | [hidePageTitle](./options/display-options.mdx#hidepagetitle)                         | Do not print page title.                                                  |
-| [hideGroupHeadings](./options/display-options.mdx#hidegroupheadings)                 | Excludes grouping by kind so all members are rendered at the same level.  |
 | [useCodeBlocks](./options/display-options.mdx#usecodeblocks)                         | Wraps signatures and declarations in code blocks.                         |
 | [expandObjects](./options/display-options.mdx#expandobjects)                         | Expand objects inside declarations.                                       |
 | [expandParameters](./options/display-options.mdx#expandparameters)                   | Expand parameters in signature parentheses to display type information.   |
diff --git a/packages/typedoc-plugin-markdown/src/options/declarations.ts b/packages/typedoc-plugin-markdown/src/options/declarations.ts
@@ -240,6 +240,8 @@ export const hidePageTitle: Partial<DeclarationOption> = {
  * This creates a flat structure where all members are displayed at the same heading level.
  *
  * @category Display
+ *
+ * @hidden
  */
 export const hideGroupHeadings: Partial<DeclarationOption> = {
   help: 'Excludes grouping by kind so all members are rendered at the same level.',
diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/comments.comment.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/comments.comment.ts
@@ -30,12 +30,12 @@ export function comment(
 
   //Add flags and summary
   if (opts.showSummary) {
-    // Add flags
     const flagsNotRendered: `@${string}`[] = [
       '@showCategories',
       '@showGroups',
       '@hideCategories',
       '@hideGroups',
+      '@disableGroups',
     ];
 
     const flags: string[] = [];
diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/container.body.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/container.body.ts
@@ -1,8 +1,13 @@
 import { heading, horizontalRule } from '@plugin/libs/markdown/index.js';
 import { MarkdownThemeContext } from '@plugin/theme/index.js';
+import {
+  isNoneSection,
+  sortNoneSectionFirst,
+} from '@plugin/theme/lib/index.js';
 import {
   ContainerReflection,
   DeclarationReflection,
+  ReflectionGroup,
   ReflectionKind,
 } from 'typedoc';
 
@@ -38,11 +43,13 @@ export function body(
         );
       } else {
         if (model.groups?.length) {
-          model.groups.forEach((group, i) => {
+          model.groups.sort(sortNoneSectionFirst).forEach((group, i) => {
             if (
               group.children.every((child) => this.router.hasOwnDocument(child))
             ) {
-              md.push(heading(options.headingLevel, group.title));
+              if (!isNoneSection(group)) {
+                md.push(heading(options.headingLevel, group.title));
+              }
               md.push(this.partials.groupIndex(group));
             } else {
               md.push(
@@ -68,6 +75,20 @@ export function body(
             kind: model.kind,
           }),
         );
+      } else if (
+        model.children?.every((child) => this.router.hasOwnDocument(child))
+      ) {
+        md.push(
+          this.partials.groupIndex({
+            children: model.children,
+          } as ReflectionGroup),
+        );
+      } else {
+        md.push(
+          this.partials.members(model.children as DeclarationReflection[], {
+            headingLevel: options.headingLevel,
+          }),
+        );
       }
     }
   }
diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/container.categories.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/container.categories.ts
@@ -1,5 +1,9 @@
 import { heading } from '@plugin/libs/markdown/index.js';
 import { MarkdownThemeContext } from '@plugin/theme/index.js';
+import {
+  isNoneSection,
+  sortNoneSectionFirst,
+} from '@plugin/theme/lib/index.js';
 import {
   DeclarationReflection,
   ReflectionCategory,
@@ -12,9 +16,11 @@ export function categories(
   options: { headingLevel: number },
 ) {
   const md: string[] = [];
-  models.forEach((category) => {
+  models.sort(sortNoneSectionFirst).forEach((category) => {
     if (category.children.every((child) => this.router.hasOwnDocument(child))) {
-      md.push(heading(options.headingLevel, category.title));
+      if (!isNoneSection(category)) {
+        md.push(heading(options.headingLevel, category.title));
+      }
       if (category.description) {
         md.push(this.helpers.getCommentParts(category.description));
       }
@@ -24,13 +30,17 @@ export function categories(
         (child) => child.kind !== ReflectionKind.Constructor,
       );
       if (categoryChildren.length) {
-        md.push(heading(options.headingLevel, category.title));
+        if (!isNoneSection(category)) {
+          md.push(heading(options.headingLevel, category.title));
+        }
         if (category.description) {
           md.push(this.helpers.getCommentParts(category.description));
         }
         md.push(
           this.partials.members(categoryChildren as DeclarationReflection[], {
-            headingLevel: options.headingLevel + 1,
+            headingLevel: isNoneSection(category)
+              ? options.headingLevel
+              : options.headingLevel + 1,
           }),
         );
       }
diff --git a/packages/typedoc-plugin-markdown/src/theme/context/partials/container.groups.ts b/packages/typedoc-plugin-markdown/src/theme/context/partials/container.groups.ts
@@ -1,5 +1,9 @@
 import { heading } from '@plugin/libs/markdown/index.js';
 import { MarkdownThemeContext } from '@plugin/theme/index.js';
+import {
+  isNoneSection,
+  sortNoneSectionFirst,
+} from '@plugin/theme/lib/index.js';
 import {
   ContainerReflection,
   DeclarationReflection,
@@ -19,7 +23,7 @@ export function groups(
     return groupTitle;
   };
 
-  model.groups?.forEach((group) => {
+  model.groups?.sort(sortNoneSectionFirst).forEach((group) => {
     if (
       group.title === i18n.kind_plural_module() ||
       group.children.every((child) => this.router.hasOwnDocument(child))
@@ -31,14 +35,18 @@ export function groups(
       if (isPackages) {
         md.push(heading(options.headingLevel, i18n.theme_packages()));
       } else {
-        md.push(heading(options.headingLevel, group.title));
+        if (!isNoneSection(group)) {
+          md.push(heading(options.headingLevel, group.title));
+        }
       }
       if (group.description) {
         md.push(this.helpers.getCommentParts(group.description));
       }
       if (group.categories) {
-        group.categories.forEach((categoryGroup) => {
-          md.push(heading(options.headingLevel + 1, categoryGroup.title));
+        group.categories.sort(sortNoneSectionFirst).forEach((categoryGroup) => {
+          if (!isNoneSection(categoryGroup)) {
+            md.push(heading(options.headingLevel + 1, categoryGroup.title));
+          }
           if (categoryGroup.description) {
             md.push(this.helpers.getCommentParts(categoryGroup.description));
           }
@@ -54,13 +62,17 @@ export function groups(
     } else {
       const isEventProps = getGroupTitle(group.title) === 'Events';
       if (group.categories) {
-        md.push(heading(options.headingLevel, getGroupTitle(group.title)));
+        if (!isNoneSection(group)) {
+          md.push(heading(options.headingLevel, getGroupTitle(group.title)));
+        }
         if (group.description) {
           md.push(this.helpers.getCommentParts(group.description));
         }
         md.push(
           this.partials.categories(group.categories, {
-            headingLevel: options.headingLevel + 1,
+            headingLevel: isNoneSection(group)
+              ? options.headingLevel
+              : options.headingLevel + 1,
           }),
         );
       } else {
@@ -72,7 +84,9 @@ export function groups(
           (child) => child.kind === ReflectionKind.EnumMember,
         );
 
-        md.push(heading(options.headingLevel, getGroupTitle(group.title)));
+        if (!isNoneSection(group)) {
+          md.push(heading(options.headingLevel, getGroupTitle(group.title)));
+        }
 
         if (group.description) {
           md.push(this.helpers.getCommentParts(group.description));
@@ -100,7 +114,9 @@ export function groups(
           if (group.children) {
             md.push(
               this.partials.members(group.children as DeclarationReflection[], {
-                headingLevel: options.headingLevel + 1,
+                headingLevel: isNoneSection(group)
+                  ? options.headingLevel
+                  : options.headingLevel + 1,
                 groupTitle: group.title,
               }),
             );
diff --git a/packages/typedoc-plugin-markdown/src/theme/lib/index.ts b/packages/typedoc-plugin-markdown/src/theme/lib/index.ts
@@ -1 +1,3 @@
 export * from './get-hierarchy-roots.js';
+export * from './is-none-section.js';
+export * from './sort-none-section-first.js';
diff --git a/packages/typedoc-plugin-markdown/src/theme/lib/is-none-section.ts b/packages/typedoc-plugin-markdown/src/theme/lib/is-none-section.ts
@@ -0,0 +1,5 @@
+import { MemberSection } from '@plugin/types/index.js';
+
+export function isNoneSection(section: MemberSection): boolean {
+  return section.title.toLocaleLowerCase() === 'none';
+}
diff --git a/packages/typedoc-plugin-markdown/src/theme/lib/sort-none-section-first.ts b/packages/typedoc-plugin-markdown/src/theme/lib/sort-none-section-first.ts
@@ -0,0 +1,12 @@
+import { MemberSection } from '@plugin/types/theme.js';
+import { isNoneSection } from './is-none-section.js';
+
+export function sortNoneSectionFirst(a: MemberSection, b: MemberSection) {
+  if (isNoneSection(a)) {
+    return -1;
+  }
+  if (isNoneSection(b)) {
+    return 1;
+  }
+  return 0;
+}
diff --git a/packages/typedoc-plugin-markdown/src/theme/navigation/navigation-builder.ts b/packages/typedoc-plugin-markdown/src/theme/navigation/navigation-builder.ts
@@ -1,7 +1,11 @@
 import { isQuoted } from '@plugin/libs/utils/index.js';
 import { OutputFileStrategy } from '@plugin/options/maps.js';
 import { MarkdownTheme } from '@plugin/theme/index.js';
-import { getHierarchyRoots } from '@plugin/theme/lib/index.js';
+import {
+  getHierarchyRoots,
+  isNoneSection,
+  sortNoneSectionFirst,
+} from '@plugin/theme/lib/index.js';
 import { MarkdownRenderer, NavigationItem } from '@plugin/types/index.js';
 import {
   DeclarationReflection,
@@ -266,16 +270,19 @@ export class NavigationBuilder {
           !this.navigationOptions.excludeCategories &&
           child.categories?.length
             ? child.categories
+                .sort(sortNoneSectionFirst)
                 ?.map((category) => {
                   const catChildren = this.getCategoryGroupChildren(category);
                   return catChildren.length
-                    ? {
-                        title: category.title,
-                        ...(this.router.hasUrl(category as any) && {
-                          path: this.router.getFullUrl(category as any),
-                        }),
-                        children: catChildren,
-                      }
+                    ? isNoneSection(category)
+                      ? [...catChildren]
+                      : {
+                          title: category.title,
+                          ...(this.router.hasUrl(category as any) && {
+                            path: this.router.getFullUrl(category as any),
+                          }),
+                          children: catChildren,
+                        }
                     : null;
                 })
                 .filter((cat) => Boolean(cat))
@@ -317,12 +324,16 @@ export class NavigationBuilder {
       }
 
       return reflection.groups
+        ?.sort(sortNoneSectionFirst)
         ?.map((group) => {
           const groupChildren = this.getGroupChildren(group);
           if (groupChildren?.length) {
             if (group.owningReflection.kind === ReflectionKind.Document) {
               return groupChildren[0];
             }
+            if (isNoneSection(group)) {
+              return [...groupChildren];
+            }
             return {
               title: group.title,
               children: groupChildren,
diff --git a/packages/typedoc-plugin-markdown/src/types/theme.ts b/packages/typedoc-plugin-markdown/src/types/theme.ts
@@ -1,4 +1,9 @@
-import { Options, ReflectionKind } from 'typedoc';
+import {
+  Options,
+  ReflectionCategory,
+  ReflectionGroup,
+  ReflectionKind,
+} from 'typedoc';
 
 /**
  * The model used to define the package metadata when in packages mode.
@@ -25,3 +30,5 @@ export interface NavigationItem {
  * Defines the template type to use for rendering.
  */
 export type RenderTemplate<T> = (data: T) => string;
+
+export type MemberSection = ReflectionGroup | ReflectionCategory;
diff --git a/packages/typedoc-plugin-markdown/test/fixtures/config.mjs b/packages/typedoc-plugin-markdown/test/fixtures/config.mjs
@@ -129,14 +129,6 @@ const config = {
       },
       {
         readme: 'none',
-        membersWithOwnFile: [
-          'Class',
-          'Interface',
-          'Enum',
-          'TypeAlias',
-          'Function',
-        ],
-        hideGroupHeadings: true,
         groupOrder: ['Functions', 'Interfaces', '*'],
         useHTMLAnchors: true,
         indexFormat: 'htmlTable',
diff --git a/packages/typedoc-plugin-markdown/test/fixtures/src/groups/has-categories.ts b/packages/typedoc-plugin-markdown/test/fixtures/src/groups/has-categories.ts
@@ -45,3 +45,13 @@ export interface CategoryCInterface2 {}
 
 export interface UnCategorizedInterace {}
 export enum UnCategorizedEnum {}
+
+/**
+ * @category None
+ */
+export interface ExplicitNoCategoryInterface {}
+
+/**
+ * @category None
+ */
+export enum ExplicitNoCategoryEnum {}
diff --git a/packages/typedoc-plugin-markdown/test/fixtures/src/groups/has-custom-groups.ts b/packages/typedoc-plugin-markdown/test/fixtures/src/groups/has-custom-groups.ts
@@ -26,3 +26,21 @@ export const variableB2 = true;
  * Default grouping
  */
 export const variableC = true;
+
+/**
+ * @group None
+ */
+export const variableNoGroup1 = true;
+/**
+ * @group None
+ */
+export const variableNoGroup2 = true;
+
+/**
+ * @group None
+ */
+export interface InterfaceNoGroup1 {}
+/**
+ * @group None
+ */
+export interface InterfaceNoGroup2 {}
diff --git a/packages/typedoc-plugin-markdown/test/fixtures/src/groups/has-disabled-groups.ts b/packages/typedoc-plugin-markdown/test/fixtures/src/groups/has-disabled-groups.ts
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/groups.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/groups.spec.ts.snap
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/navigation.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/navigation.spec.ts.snap
diff --git a/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap b/packages/typedoc-plugin-markdown/test/specs/__snapshots__/urls.spec.ts.snap
diff --git a/packages/typedoc-plugin-markdown/test/specs/groups.spec.ts b/packages/typedoc-plugin-markdown/test/specs/groups.spec.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'typedoc-plugin-markdown': patch
 +---
++
 +- Added support for TypeDoc's v0.28.2 features `@group none`, `@category none` and `@disableGroups`.
Original file line number	Diff line number	Diff line change
`@@ -240,6 +240,8 @@ export const hidePageTitle: Partial<DeclarationOption> = {`
`240`	`240`	`* This creates a flat structure where all members are displayed at the same heading level.`
`241`	`241`	`*`
`242`	`242`	`* @category Display`
	`243`	`+ *`
	`244`	`+ * @hidden`
`243`	`245`	`*/`
`244`	`246`	`export const hideGroupHeadings: Partial<DeclarationOption> = {`
`245`	`247`	`help: 'Excludes grouping by kind so all members are rendered at the same level.',`
Original file line number	Diff line number	Diff line change
`@@ -1 +1,3 @@`
`1`	`1`	`export * from './get-hierarchy-roots.js';`
	`2`	`+export * from './is-none-section.js';`
	`3`	`+export * from './sort-none-section-first.js';`