Download page Structure Your Help Center.
Structure Your Help Center
In this section you will learn about what options you have when it comes to structuring your content spaces and displaying them using the Help Center theme.
Scroll Viewport generally operates at a space level. On the one hand, this means any viewport created within a space accesses all of the pages (or blog posts) in that space, while respecting Confluence permissions. On the other hand, in order to make a page or blog post available in the Viewport view, a viewport must be created in that space.
A viewport collection is a concept in Scroll Viewport that allows the grouping of related viewports. You can learn more about the viewport collection placeholder in the development documentation.
A viewport collection is an unordered set of viewports with one of the viewports in the set being the root viewport. Non-root viewport are referred to as member viewports. To define a viewport collection, the root viewport must be configured first. This is done in the URL tab of the viewport configuration.
Once the root viewport is defined, member viewports are defined implicitly using the path. A viewport is a member of a collection if the following conditions are met:
- It has the same domain as the root viewport of a collection.
- Its path starts with the root's path.
Example: If a root path is domain.com/docs/, then domain.com/docs/product-one/ is member of the collection. In this example "/docs/product-one/" is the member viewport's defined path.
By entering only a "/" as the path for the root viewport, all viewports under a certain domain are considered members of the collection.
Viewport collections in the Help Center theme
The Help Center theme behaves differently depending on whether a viewport in which it is selected is a root viewport or a member viewport.
Root viewports with the Help Center theme display their space home page as a portal page listing member viewports. Other pages are displayed regularly in the article view. Searched performed in the root space search all of the member spaces, too.
Non-root viewports with the Help Center theme active display their home page as a space home page listing their pages. Other pages are displayed regularly in the article view.
Though using the same copy of a Help Center is recommended, it is technically possible to combine different themes within a viewport collection.
Setting Up Help Center Structure
Single-space Help Center
Creating a help center with only one space doesn't require any additional steps to the initial setup.
A single-space help center might be sufficient if all of the documentation that one is publishing is contained to one space, which is not uncommon in smaller teams. It is also possible to create multiple single-space help centers in one instance, even under different domains. This way those help center will appear entirely independent.
Multi-space Help Center
The multi-space help center is the right approach if you are documenting multiple products in a space each or have a documentation that is broken up into separate spaces, but want to display it in a unified way with a unified search.
As the diagram above indicates, a multi-space help center creates a hierarchy of spaces with two hierarchy levels. The root space acts like a portal that forwards visitors into the member spaces though navigation as well as search. The way the two levels are used is up to the user.
One theme and multiple themes
When setting up your help center, you have two ways of handling the theme:
- Use one global copy of the Help Center theme
- Use multiple, different copies of the Help Center theme
Though we recommend the first approach to keep it simple, there is nothing stopping you from creating dedicated copies of the Help Center theme and styling them different per product.
The following instructions assume you are documenting one product per member space and combine those into one help center. Also, they assume the following prerequisites:
- You have multiple spaces of content in Confluence.
- You have created and customized your copy of the Help Center theme and have made it global.
Setup a Root Space for your Help Center
- Create a blank site space with a Space name of your choice.
- Create a viewport on that space using your global Help Center theme copy.
- Choose a path you would like the help center to be under.
- On the URL tab, check Enable viewport collection under this path.
- Choose Save to apply your changes.
Add Member Spaces to the Help Center
To group the spaces containing help center content together, and to form understandable help center URLs, you'll set up each space's viewport to be a member of the collection under the root space you just created.
- Create a viewport or choose Configure on an existing viewport.
- Make sure your global Help Center theme copy is selected.
- On theURL tab:
- Enter the Domain name for the help center. (Same domain as root space.)
- In Path, enter the path for the root space viewport followed by a "/" and the path for the given space.
For example, if your root space viewport path is "/help", the path for this space could be "/help/app-name".
- Choose Save to apply your changes.
- Repeat these steps for all spaces you want to add to your help center.