#3042·typedoc

sort: ["source-order"] should apply to group ordering, not just group members

Author: knoanCreated Nov 19, 2025Updated Nov 29, 2025

Current Behavior

When sort: ["source-order"] is configured in typedoc.json, it only affects the ordering of items within groups, not the groups themselves. Groups are always ordered alphabetically.

Example configuration:

json
{
  "sort": [
    "source-order"
  ]
}

Source code order:

typescript
/**
 * @group Comparators
 */
export function ascending() { }

/**
 * @group Factories
 */
export function by() { }

/**
 * @group Combinators
 */
export function reverse() { }

Generated docs show groups in alphabetical order:

  1. Combinators
  2. Comparators
  3. Factories

Expected Behavior

When sort: ["source-order"] is configured, groups whose order is not explicitly specified in groupOrder should be sorted by source order rather than alphabetically:

  1. Comparators (first @group in source)
  2. Factories (second @group in source)
  3. Combinators (third @group in source)

Note: groupOrder should maintain precedence when explicitly specified. This is about the fallback behavior for unspecified groups.

Current Workaround

Must explicitly configure groupOrder:

json
{
  "sort": [
    "source-order"
  ],
  "groupOrder": [
    "Comparators",
    "Factories",
    "Combinators",
    "*"
  ]
}

Proposed Solution

Modify group sorting behavior to respect the sort option when groupOrder doesn't explicitly specify all groups:

  • Groups listed in groupOrder maintain their explicit order (preserves existing behavior)
  • Unlisted groups fall back to sort: ["source-order"] if configured, alphabetically otherwise
  • Update groupOrder documentation from "Groups whose order is not specified will be sorted alphabetically" to "Groups whose order is not specified will be sorted by source order if sort: ["source-order"] is configured, alphabetically otherwise."