---
title: "Setting up hierarchical spaces"
canonical: "https://support.appfire.com/space/COMALACM/656676531/Setting%20up%20hierarchical%20spaces"
format: markdown
---
> Macro (aura-html)
## Overview
Although Confluence provides access to the page hierarchy in a space, the default is a flat hierarchy. As your content grows, spaces increase—this becomes harder and harder to manage. Grouping spaces together can help users manage the content.
The Comala Metadata app lets you to define space hierarchies by utilizing space metadata. A single piece of space metadata can be attached to a space's home page, indicating the key of its parent space.
## Macros
The Comala Metadata App provides a number of macros to support the process of setting up a space hierarchy:
- [parent-space](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655759943)
- [space-hierarchy](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655759770)
- [space-breadcrumbs](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/656677781)
- [user-space](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655891780)
## Steps
Using these macros, there are three steps to set up hierarchical spaces:
- [Create a root space](#Settinguphierarchicalspaces-rootspace)
- [Add parent metadata to every other space](#Settinguphierarchicalspaces-parentspacemetadata)
- [Update the space breadcrumbs](#Settinguphierarchicalspaces-spacebreadcrumb)
In addition to having a root space, the [user-space](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655891780) macro can be used to define a parent space for the personal spaces in the instance.
## Create a root space > Macro (anchor)
The first thing to do is to decide upon a root space for a space hierarchy. Most non-hierarchical wiki installations do not currently have one, so you should create one.
For example, in our company instance for **Stars Like Dust, **the following spaces have been created:
| **Space** | **Parent** |
| --- | --- |
| Stars Like Dust | Root space |
| People | Stars Like Dust |
| Quality | Stars Like Dust |
| Development | Stars Like Dust |
The root space should probably have the same name as the wiki itself, because it is shown as the root of the breadcrumb.
In addition, it would be good to set the root space to be the site’s home page. You can do this in the Confluence global **Administration** under **Configuration/General Configuration**.
## Add parent metadata to every other space> Macro (anchor)
For all the spaces you require in the hierarchy, add the {parent-space} macro to the home page of each space, adding the space key for the root space to the macro placeholder:
In this example, the space key for the selected root space **Stars Like Dust** is `SLD`, and the addition of the **parent-space macro** sets the current space as a child of this `SLD` space.
Once added to the page, the hierarchy metadata is available to other metadata macros.
Add the [space-hierarchy](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/656677781) macro to the **Stars Like Dust** home page:
With the space key empty, this will display the hierarchy set for the spaces relative to the current page.
If any of these spaces in the hierarchy have further descendants, you can add the metadata to the child pages with the space key for the appropriate parent.
For example, if you require project spaces for **Development**, these can be added into a secondary level of the hierarchy
| **Space** | **Parent** |
| --- | --- |
| Stars Like Dust | Root space |
| Development | Stars Like Dust |
| Project Ascension | Development |
| Project Stellar | Development |
To create the hierarchy, the [parent-space](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655759943) macro is added to each of the project space homepages, configured with the space key of the **Development** space:
The [space-hierarchy](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/656677781) macro to the **Stars Like Dust** home page will now display:
#### Add the space-breadcrumbs macro> Macro (anchor)
The [space-breadcrumbs](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/656677781) macro analyses the space hierarchy information. It can be added to any page.
The simplest way is to add the macro to a page:
This displays a space breadcrumb from the current page (**Development**) to the chosen option of the instance **Dashboard**.
This is more useful if added automatically for each page. Unfortunately, the macro cannot update the site breadcrumb. However, this can be done by adding the macro using one of the **Look and Feel** options in Confluence global administration:
- add the macro to the header in the **Sidebar, Header and Footer** option
This displays the space breadcrumb for all the pages in each of the spaces in the hierarchy (in this example, within a titled info message panel):
The breadcrumb is displayed according to the location of the space of the current page in the defined space hierarchy.
> 📝 If there are any spaces in the instance that are not in the set hierarchy, as the header is a global setting, this breadcrumb is still present on the pages in that space. The breadcrumb renders according to the individual space with no reference to the set space hierarchy
To avoid the breadcrumbs being displayed in non-hierarchical spaces, the [space-breadcrumbs](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/656677781) macro must be added to the global **Layout **file or stylesheet. For example, it could be part of custom HTML or CSS for the layout, with a conditional display of the breadcrumb on the presence of the space in the set hierarchy.
## Create a 'Users' space
In addition to having a root space, it seems to be useful to also have a **Users** space. This is conceptually the parent space of every personal space, and helps to provide another level of structure if required.
If you require a user space, you should put the following metadata macros into the home page for the designated **Users** space:
- [parent-space](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655759943) adds the space to the hierarchy
- [user-space](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655891780) sets the space as the home page for any personal spaces in the instance
The home page of the current space is now the root of all user spaces. It also has the instance root space as its parent space
A useful option is to add the [users-report](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655891474) macro directly onto this page (but be careful, as this assumes that you don't have many users).
The [users report](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655891474) can be configured to add internal metadata for each user and the app custom space metadata from each user space.
In the example, only the user **admin** has a personal user space. Space metadata has been added to the personal space of the user **admin** to record their location.
## Related macros
> Macro (contentbylabel)
## Related pages
- [Adding metadata to a space](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655988362)
- [Using metadata in a space](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/655758361)
- [Using metadata to define space hierarchies](https://appfire.atlassian.net/wiki/spaces/COMALACM/pages/656578613)