Document group aliases and content ordering configuration

Add documentation for the new group aliases and contentOrder options to the catalog customization guide. Signed-off-by: Patrik Oldsberg <poldsberg@gmail.com>
2026-02-26 10:15:35 +01:00
parent 3eac7e204c
commit 3be516b73a
2 changed files with 44 additions and 0 deletions
@@ -728,6 +728,49 @@ Notes:
 - Icons for groups and tabs are resolved via the app's IconsApi. When using a string icon id (for example `"dashboard"`), ensure that the corresponding icon bundles are enabled/installed in your app (see the [IconBundleBlueprint documentation](https://backstage.io/api/stable/variables/_backstage_plugin-app-react.IconBundleBlueprint.html)).
 - Group icons are only rendered if `showNavItemIcons` is set to `true`.

+### Content ordering within groups
+
+By default, content items within each group are sorted alphabetically by title. You can change this with the `contentOrder` option, which supports two modes:
+
+- **`title`** (default) — sort alphabetically by the content extension's title (case-insensitive).
+- **`natural`** — preserve the natural extension discovery/registration order.
+
+A page-level `contentOrder` sets the default for all groups, and individual groups can override it:
+
+```yaml
+app:
+  extensions:
+    - page:catalog/entity:
+        config:
+          # Default content order for all groups
+          contentOrder: title
+
+          groups:
+            - documentation:
+                title: Docs
+                # Override: keep natural order for this group
+                contentOrder: natural
+```
+
+Note that content ordering only applies to content items within groups. Ungrouped tabs (those not matching any group definition) always retain their natural order.
+
+### Group aliases
+
+Groups can declare `aliases` — a list of other group IDs that should be treated as equivalent. Any entity content extension targeting an aliased group ID will be included in the aliasing group. This is useful when renaming or merging groups without having to reconfigure individual extensions:
+
+```yaml
+app:
+  extensions:
+    - page:catalog/entity:
+        config:
+          groups:
+            - develop:
+                title: Develop
+                # Content targeting 'development' will appear in this group
+                aliases:
+                  - development
+```
+
 ### Overriding or disabling a tab's group (per extension)

 Each entity content extension (tabs on the entity page) can declare a default `group` in code. You can override or disable this per installation in `app-config.yaml` using the extension's config: