TypeStrong / TypeStrong/typedoc
sort: ["source-order"] should apply to group ordering, not just group members
Nobody has claimed this yet.
- Dominant language
- TypeScript
- Stars
- 8.5k
- Forks
- 775
- PR merge metrics
- No merged PRs in 30d
Description
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:
{
"sort": [
"source-order"
]
}
Source code order:
/**
* @group Comparators
*/
export function ascending() { }
/**
* @group Factories
*/
export function by() { }
/**
* @group Combinators
*/
export function reverse() { }
Generated docs show groups in alphabetical order:
- Combinators
- Comparators
- 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:
- Comparators (first
@groupin source) - Factories (second
@groupin source) - Combinators (third
@groupin source)
Note: groupOrder should maintain precedence when explicitly specified. This is about the fallback behavior for unspecified groups.
Current Workaround
Must explicitly configure groupOrder:
{
"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
groupOrdermaintain 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."
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with the groupOrder documentation in organization.md and trace the group-sorting behavior described in the issue. Verify that explicit groupOrder entries retain precedence, that unspecified groups use source order only with sort: ["source-order"], and that alphabetical ordering remains the fallback; update the documented behavior when this is complete.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation
- Issue type
- Bug
- Difficulty
- 3/5
- Estimated time
- 1-2 days
- Activity status
- Stale
- Clarity
- Clearly specified
- Newbie friendliness
- 48/100