diff --git a/docs/content/docs/2.collections/2.types.md b/docs/content/docs/2.collections/2.types.md
index c01e74ec5..11b66cfec 100644
--- a/docs/content/docs/2.collections/2.types.md
+++ b/docs/content/docs/2.collections/2.types.md
@@ -90,6 +90,8 @@ Here is the corresponding schema applied:
 You can override any of these fields by defining them in the collection’s schema.
 ::
 
+The `navigation` object is also the place for custom metadata consumed by [`queryCollectionNavigation`](/docs/utils/query-collection-navigation). In page frontmatter or `.navigation.yml`, fields such as `section`, `group`, or `badge` should be nested under `navigation`, and they will be exposed on the generated `ContentNavigationItem`.
+
 ## Data type
 
 ```ts
diff --git a/docs/content/docs/4.utils/2.query-collection-navigation.md b/docs/content/docs/4.utils/2.query-collection-navigation.md
index 8781b1baf..c709c8622 100644
--- a/docs/content/docs/4.utils/2.query-collection-navigation.md
+++ b/docs/content/docs/4.utils/2.query-collection-navigation.md
@@ -30,9 +30,22 @@ You can add metadata to a directory using a `.navigation.yml` file.
 
 ```yml [.navigation.yml]
 title: Getting Started
-icon: i-lucide-square-play
+navigation:
+  icon: i-lucide-square-play
 ```
 
+Directory-level navigation fields should be defined under `navigation:`. These values are merged into the returned `ContentNavigationItem`, so custom flags can live there as well.
+
+```yml [.navigation.yml]
+title: Getting Started
+navigation:
+  icon: i-lucide-square-play
+  section: true
+  badge: New
+```
+
+With that config, `queryCollectionNavigation()` returns a navigation item for the directory with `icon`, `section`, and `badge` available on the item object.
+
 ## Type
 
 ```ts