clean-jsdoc-theme

@category — group a symbol in the sidebar

@category puts a symbol's generated page into an explicit sidebar group instead of its default kind section (Classes, Modules, Namespaces, …):

CODE
/**
 * @category Core
 */
export class Parser {}

Parser now lives under a Core group rather than under Classes.

@category is an unknown tag — set tags.allowUnknownTags: true in your jsdoc.json or JSDoc strips it before the theme runs. See the overview. (TypeDoc needs no flag.)

The path grammar

parseCategory (in generate-site.ts) splits the tag text on whitespace, then:

  • The leading run of plain tokens is the group path, joined with a single space.
  • Parsing switches to options at the first token containing =. Everything from there on is key=value.
  • A literal / is what nests a group. Spaces do not nest.

Spaces stay in the name; / nests

This is the subtle part. A space is just part of the group name — only / creates a parent ▸ child relationship.

CODE
/** @category Getting Started */
export class Intro {}

→ one flat group literally named Getting Started (the space is kept).

CODE
/** @category Core/Parsing */
export class Lexer {}

→ nests the page under Core ▸ Parsing.

You can nest as deep as you like — @category Core/Parsing/Internals → Core ▸ Parsing ▸ Internals.

First @category wins

If a symbol carries more than one @category, the first one is used; the rest are ignored.

Inline order=

The only @category option today is order — the within-group sort key:

CODE
/** @category Core/Parsing order=1 */
export class Lexer {}

/** @category Core/Parsing order=2 */
export class Token {}

Lexer sorts before Token inside Core ▸ Parsing. The path is the leading tokens; options follow the first =, so Getting Started order=1 is the group Getting Started with order=1.

A missing or non-numeric order is left undefined — the page then sorts last, alphabetically, like an untagged one.

Worked examples

CODE
/** @category Core */
export class A {}                 // → Core

/** @category Core/Schema order=1 */
export class Point {}             // → Core ▸ Schema, first

/** @category Data Pipeline */
export class Stage {}             // → "Data Pipeline" (one group; space kept)

/** @category Advanced/Internals order=10 */
export class Cache {}             // → Advanced ▸ Internals, order 10

Combining with @order

order= inline on @category and the standalone @order tag both feed the same sort key. When a symbol has both, the inline @category … order= wins — see the precedence rule on the @order page.

How it shapes the sidebar

@category is one lever in the theme's single sidebar-ordering engine — every entry carries a group path and an optional order. The prose counterpart is a guide page's group frontmatter (same /-nesting rules). The full model — nested paths, leaf-vs-branch ordering, clubSidebarItems, sectionOrder, docGroups, and menu — is in Structure your sidebar.

See also