Restructure tree documentation into sub-articles

17/umbraco-cms/.gitbook.yaml

@@ -154,4 +154,8 @@ redirects:
     customizing/extending-overview/extension-types/modals/confirm-dialog: customizing/utilities/modals/confirm-dialog.md
     customizing/searchable-trees: customizing/overview.md
     customizing/section-trees: customizing/overview.md
+    customizing/extending-overview/extension-types/tree: customizing/extending-overview/extension-types/tree/README.md
+    customizing/extending-overview/extension-types/tree-item: customizing/extending-overview/extension-types/tree/README.md
+    customizing/extending-overview/extension-types/stores-and-repositories/tree-store: customizing/extending-overview/extension-types/tree/tree-repository.md
+    customizing/extending-overview/foundation/repositories/repository-types/tree-repository.md: customizing/extending-overview/extension-types/tree/tree-repository.md
 

17/umbraco-cms/SUMMARY.md

@@ -188,7 +188,10 @@
       * [Section](customizing/extending-overview/extension-types/sections/section.md)
       * [Section Sidebar](customizing/extending-overview/extension-types/sections/section-sidebar.md)
       * [Section View](customizing/extending-overview/extension-types/sections/section-view.md)
-    * [Trees](customizing/extending-overview/extension-types/tree.md)
+    * [Trees](customizing/extending-overview/extension-types/tree/README.md)
+      * [Tree Repository](customizing/extending-overview/extension-types/tree/tree-repository.md)
+      * [Tree Models](customizing/extending-overview/extension-types/tree/tree-models.md)
+      * [Trees & Workspaces](customizing/extending-overview/extension-types/tree/trees-and-workspaces.md)
     * [Workspaces](customizing/extending-overview/extension-types/workspaces/README.md)
       * [Workspace Actions](customizing/extending-overview/extension-types/workspaces/workspace-editor-actions.md)
       * [Workspace Action Menu Items](customizing/extending-overview/extension-types/workspaces/workspace-action-menu-items.md)
@@ -219,7 +222,6 @@
       * [Collection Repository](customizing/foundation/repositories/repository-types/collection-repository.md)
       * [Detail Repository](customizing/foundation/repositories/repository-types/detail-repository.md)
       * [Item Repository](customizing/foundation/repositories/repository-types/item-repository.md)
-      * [Tree Repository](customizing/foundation/repositories/repository-types/tree-repository.md)
   * [States](customizing/foundation/states.md)
   * [Routes](customizing/foundation/routes.md)
   * [Backoffice Localization](customizing/foundation/localization.md)

17/umbraco-cms/customizing/extending-overview/extension-types/menu-item.md

@@ -199,6 +199,27 @@ export const menuItemManifest: ManifestMenuItem = {
 ```
 {% endcode %}
 
+#### Hiding the Tree Root
+
+To display tree items at the root level without a parent folder node, add `hideTreeRoot: true` to the menu item's meta:
+
+```typescript
+{
+    type: 'menuItem',
+    kind: 'tree',
+    alias: 'My.MenuItem.Tree',
+    meta: {
+        treeAlias: 'My.Tree',
+        menus: ['My.Menu'],
+        hideTreeRoot: true,
+    },
+}
+```
+
+{% hint style="info" %}
+The `hideTreeRoot` property must be set on the menuItem manifest, not the tree manifest.
+{% endhint %}
+
 ## Custom Menu Items
 
 {% hint style="info" %}

17/umbraco-cms/customizing/extending-overview/extension-types/tree/README.md

@@ -0,0 +1,141 @@
+---
+description: A guide to creating a custom Tree in Umbraco
+---
+
+# Trees
+
+{% hint style="info" %}
+**New to sidebar navigation?** Read [Menus](../menu.md) and [Menu Items](../menu-item.md) first. For basic, static navigation you can use Menu Items alone. Trees are for **data-driven hierarchical structures** - use them when your Menu needs to display dynamic content from an API.
+{% endhint %}
+
+{% hint style="warning" %}
+To create a working Tree in the Backoffice, you need to understand three things:
+
+1. **[Populating Trees](#populating-trees)** - How to populate a Tree with data.
+2. **[Displaying Trees](#displaying-trees)** - How to display Trees and connect them to Menus to appear in the Section Sidebar or elsewhere.
+3. **[Trees and Workspaces](#trees-and-workspaces)** - How to navigate to Workspaces by clicking Menu Items.
+{% endhint %}
+
+## Populating Trees <a href="#populating-trees" id="populating-trees"></a>
+
+Trees get their data from a **Repository**. The Repository implements methods to return Tree Items and is referenced by the Tree Manifest via `repositoryAlias`.
+
+### Register the Repository
+
+```typescript
+{
+    type: 'repository',
+    alias: 'My.Tree.Repository',
+    name: 'My Tree Repository',
+    api: () => import('./my-tree.repository.js'),
+}
+```
+
+### Repository Implementation
+
+Create a Repository that implements the `TreeRepository` interface. The interface below is simplified for clarity and omits return types and arguments. See full interfaces in the [UI API Documentation](https://apidocs.umbraco.com/v17/ui-api/interfaces/packages_core_tree.UmbTreeRepository.html)
+
+```typescript
+interface UmbTreeRepository {
+    requestTreeRoot();
+    requestTreeRootItems();
+    requestTreeItemsOf();
+    requestTreeItemAncestors();
+}
+```
+
+For detailed implementation guidance, see:
+
+- **[Tree Repository](./tree-repository.md)** - Full repository implementation with static data example.
+- **[Tree Models](./tree-models.md)** - `UmbTreeItemModel` and `UmbTreeRootModel` interfaces.
+
+---
+
+## Displaying Trees <a href="#displaying-trees" id="displaying-trees"></a>
+
+### Tree Manifest
+
+Register your tree with a Manifest. The `repositoryAlias` links to how the Tree gets its data:
+
+```typescript
+{
+    type: 'tree',
+    kind: 'default',
+    alias: 'My.Tree',
+    name: 'My Tree',
+    meta: {
+        repositoryAlias: 'My.Tree.Repository',
+    },
+}
+```
+
+### Tree Item Manifest
+
+Tree-items define how individual items render. Use `kind: 'default'` for standard rendering:
+
+```typescript
+{
+    type: 'treeItem',
+    kind: 'default',
+    alias: 'My.TreeItem',
+    forEntityTypes: ['my-tree-root', 'my-tree-item'],
+}
+```
+
+{% hint style="info" %}
+Include both your root entity type and item entity type in `forEntityTypes` so the Tree Item renderer handles all nodes in your Tree.
+{% endhint %}
+
+### Standalone Rendering
+
+Trees can be rendered directly in custom components using the `<umb-tree>` element:
+
+```html
+<umb-tree alias="My.Tree"></umb-tree>
+```
+
+### Connecting to a Menu
+
+Trees can also provide hierarchical data to **Menu Items**, which display the navigation you see in the Backoffice Section Sidebar. 
+To register your Tree-based Menu Item use the `kind: 'tree'` in the Menu Item Manifest. 
+
+```typescript
+{
+    type: 'menuItem',
+    kind: 'tree',
+    alias: 'My.MenuItem.Tree',
+    name: 'My Tree Menu Item',
+    weight: 100,
+    meta: {
+        label: 'My Tree',
+        icon: 'icon-folder',
+        entityType: 'my-tree-root',
+        menus: ['My.Menu'] // The Menu alias where this item should appear,
+        treeAlias: 'My.Tree',
+        hideTreeRoot: true,  // Optional: show items at root level
+    },
+}
+```
+
+Examples of built-in Menus include:
+
+* Content - `Umb.Menu.Content`
+* Media - `Umb.Menu.Media`
+* Advanced Settings - `Umb.Menu.AdvancedSettings`
+
+See [Menu Items (Tree kind)](../menu-item.md#tree) and [Section Sidebar](../sections/section-sidebar.md) for the complete setup.
+
+---
+
+## Trees and Workspaces <a href="#trees-and-workspaces" id="trees-and-workspaces"></a>
+
+When users click a Tree Item, Umbraco navigates to a **Workspace** to edit that item. The `entityType` in your Tree Items must match the `meta.entityType` in your Workspace Manifest.
+
+See **[Trees & Workspaces](./trees-and-workspaces.md)** for setup details and troubleshooting.
+
+---
+
+## Further Reading <a href="#further-reading" id="further-reading"></a>
+
+- [Umbraco UI Examples - Trees](https://github.com/umbraco/Umbraco-CMS/tree/main/src/Umbraco.Web.UI.Client/examples/tree) - Working examples in the Umbraco repository.
+- [Workspaces](../workspaces/README.md) - Creating Workspace extensions.