This guide provides a detailed walkthrough for setting up the Arboretum Sitemap App in Contentful. Since Arboretum operates entirely on your existing Contentful data, your content structure is crucial and may require minor adjustments during the setup process.
Installing the Arboretum Sitemap App
To install the Arboretum Sitemap App, visit the Contentful Marketplace. During installation, you'll be prompted to select the appropriate space and environment as the target location for the Arboretum.
Once added to your space, you'll need to provide a license key, which can be obtained for free on the Arboretum license generator page. After submitting the form, the key will be sent to your email. Note that the license key is specific to each space and environment. If you need an Arboretum in another environment, you'll need to generate a new key.
After verifying the license key, you'll proceed to the setup screen, where you can configure the app to suit your Contentful environment.
Arboretum can run on both regular and alias environments, but not simultaneously. If you configure a license for your master (alias) environment, Arboretum will not work in the target environment for that alias (and vice versa).
Installation Modes
Arboretum offers three installation modes. These options are designed to ensure flexibility, regardless of whether you are starting fresh or working with an existing content setup.
Manual installation:
Recommended for production environments that have existing content. The manual installation mode allows users to have full control over the setup process. In this mode, Arboretum does not touch your content model in Contentful. You are responsible for adjusting it (if needed) and for configuring the Arboretum. If you choose this installation type, later in the process you will be asked to select at least one content model that represents pages, so the sitemap can be generated based on it. You will need to specify which fields from the content model should be used for the slug, page title, and structure (either child pages or parent page).
Best for: Production environments, environments with existing, complex page models.
Semi-automatic installation:
This installation mode is ideal for non-production environments with existing content models. Unlike the automatic installation, the semi-automatic option will not create sample content but will try to automatically adjust the existing configuration to integrate Arboretum to your project.
Best for: Non-production environments with existing content.
Automatic installation:
This is the simplest and most efficient installation mode, recommended for environments that are new and do not yet contain any content (or any content related to pages). Arboretum automatically creates basic page content models together with sample content. As a result, you can see the sitemap in the Arboretum App immediately after installation.
Best for: New projects or environments with no pre-existing content.
Relationships Between Parent and Child Pages
The Arboretum Sitemap App helps manage your website structure using your Contentful data. To enable this, your content must encode the parent-child relationship between pages. There are two main methods to establish this relationship: Child-to-Parent linking (the child page links to its parent) or Parent-to-Children linking (the parent page links to its children).
Child-to-Parent Link (recommended)
When a new page is being created, you can simply assign a parent page to it, establishing the relationship without needing to adjust or republish the parent page. For Arboretum users, this means the new page is automatically added to the sitemap as soon as the parent page is set.
Drawback: you lose the order of child pages in your page tree. This can be an issue if your website depends on a specific order of pages in a sitemap (eg. for displaying navigation). We suggest that you not rely on the order of nodes in a sitemap for any newly developed code.
Key Benefits:
Simplified Page Management: Adding a new page only requires setting the parent field on the child page, leaving the parent page unchanged and avoiding multiple updates.
Faster Updates: Since the parent page doesn't need to be modified or republished, the process is quicker and less disruptive to existing content.
Scalability: This method allows easier management of individual pages in large projects without breaking the overall hierarchy.
Use Case: Ideal for most projects, especially those that frequently add new content. It's also well-suited for scenarios where pages are automatically created by synchronizing data from third-party systems.
Parent-to-Children Links
The Parent-to-Children links model allows you to manage the relationship between parent and child page from the parent level. In this setup, you can select and link multiple child pages at once. For example, on a homepage, you can assign all its direct child pages in one step. The ability to keep child page references in a list at the parent level also lets you control the order of the child pages as needed.
Drawback: This model requires manual hierarchy management at the parent level. Each time a new child page is added, the parent page must be updated and republished for the changes to reflect in the sitemap. This results in additional work and can complicate workflows that require approval.
Key Benefits:
Simplified Child Management: Multiple child pages can be assigned under a single parent page at once.
Preserved Child Order: As children are stored in a list in the parent page, their order is maintained at each level of the sitemap.
Use Case: Useful for legacy setups or projects where the order of content pages in a sitemap is crucial.
Configuring Page Relationships in Arboretum
When using automatic or semi-automatic configuration, the content model will be created or adjusted based on either the Child-to-Parent or Parent-to-Children relationship modes. You simply need to choose which option you prefer (we recommend Child-to-Parent).
For manual configuration, Arboretum will store your chosen method for encoding page relations, but the rest of the setup must be completed by you based on that choice.
If you ever need to switch between different page relation methods, you will need to reinstall the Arboretum App, as the system does not currently support toggling between these options.
Arboretum Configuration
If you selected automatic installation mode, you just need to make sure that the configuration is saved (the "Save" button is in the upper right corner) and you are good to go. If, on the other hand, you’ve selected semi-automatic or manual installation mode, please make sure you familiarize yourself with configuration options as proper setup is crucial for Arboretum to be able to derive a site structure for you.
Pages configuration
In this step you’ll configure which content types represent pages in your setup. You can have multiple content types defined as pages, but configuring at least one content type is required.
Once you add your page content type, three drop-downs will appear, allowing you to select fields from your content model that Arboretum will use as:
Slug: This represents part of a path that identifies a specific page. In the Contentful model, it should be defined as a required “Short text” field.
Page title: This represents human-readable text displayed in the Arboretum App to help navigate and identify pages. In the Contentful model, it should be defined as a required “Short text” field.
Parent page (only in “child to parent” page relations mode): It is a field based on which the sitemap structure is created. It encodes relations between pages. In the Contentful model, it should be defined as a single “Reference” field.
Child pages (only in “parent to children” page relations mode): Serves exactly the same page relations purpose as Parent page field described above. In the Contentful model, it should be defined as a multi “Reference” field.
All mentioned fields can be marked as localisable in your content model, allowing you to shape your content types according to your specific needs. With Arboretum, your sitemap can have localized paths, page titles and even the overall structure. Localization settings can be changed at any time, and Arboretum will automatically reflect these updates while preserving Contentful's locale fallback mechanism.
Redirects configuration (optional)
Redirects configuration is optional, and unlike page configuration, only one content type can be configured. The flow is similar to page configuration: once you select a content type, additional drop-downs appear for you to hint Arboretum on which fields should be used as:
Page: This represents the reference to the page that the redirect leads to. In the Contentful model, it should be defined as a single “Reference” field.
Redirect title: This represents human-readable text displayed in the Arboretum App. In the Contentful model, it should be defined as a required “Short text” field.
Path: This represents the full path of the redirect. In the Contentful model, it should be defined as a required “Short text” field.
Type: Should accept only two values: "redirect" or "alias". We recommend setting this as a validation in Contentful. From the Arboretum app's perspective, these two types have no special effects, but the distinction can be reflected on your website. In the Contentful model, it should be defined as a required “Short text” field.
Just like with page content types, fields of the redirect content type can be localisable as needed.
Preview setup (optional)
In addition to visual representation of a website tree, the Arboretum App offers additional features. One of these are links to both the published and preview versions of your website. In order to configure it, you need to define the URLs, which will act as prefixes that the Arboretum App uses to generate proper links. By default http://localhost:3000 will be used.
Besides the preview, each sitemap node includes a link to edit the corresponding entry. If you use Compose and would like Arboretum to open Compose as your entry editor, please enable the "use Compose" switch. After making changes, please remember to click the "Save" button in the upper right corner to persist the configuration.
Select home page entry
After finalizing the Arboretum configuration, there is one last step: selecting the root (or home) of your sitemap. You can do this by adding a public tag named "Page: Home" (or a differently named tag with Tag ID pageHome) to one of your page entries. This tag indicates to the Arboretum where to start building the sitemap structure. Ensure that only one page entry has this tag assigned.
Locales configuration
For each locale defined in Contentful, Arboretum creates an independent sitemap structure. Depending on your configuration, these sitemaps may be very similar, identical, or completely different. Each Contentful locale has a unique code, which Arboretum uses as a path prefix. For example, pages in the "en-US" locale have paths that start with /en-US/, and pages in the "de" locale have paths that start with /de/.
Final thoughts
We hope that the journey through the deep details of Arboretum Sitemap App configuration wasn’t too overwhelming. Remember, if your case allows for that, you can always choose automatic installation mode and let Arboretum configure itself!
Happy Sitemapping!
Bonus: Arboretum Extensions For Your Editor's Convenience
Beside the main application, Arboretum Sitemap App comes with two additional extensions that can simplify your editor’s life.
Field level extension configuration
The Arboretum App provides field-level extensions to simplify creating references to pages in your content model using visual tree structure. These extensions can be enabled for both single and multi-reference fields. To enable it, go to the content model configuration, select a reference field, click "Edit", navigate to the "Appearance" section, and choose Arboretum. After that, when you create a reference, a sitemap tree will appear in a dialog instead of the native entry selector, allowing you to select the desired node from a sitemap instead from a flat list of pages.
Sidebar extension configuration
The Arboretum sidebar extension is especially useful when editing your page entries in Contentful. For a selected mode and a locale of your choice, it creates a preview link to quickly see how the edited page looks like. To configure this extension, go to the page content type, select "Sidebar", and add the Arboretum App. After that, when you edit an entry of this type, the Arboretum sidebar app will appear, allowing you to open a preview (assuming the entry exists in the sitemap).
Anna Machalska
ISMS Responsible/Software Tester, Bright IT