Multisite support is an Enterprise Edition feature provided by the Extended Templating Kit module. It allows you to manage multiple websites in a single Magnolia instance. Each site has its own site definition which can apply unique templates, themes, variations, domains and locales to the site. Besides making each site unique, the multisite feature lets you inherit features from another site.

You can use multisite support for microsites, campaigns, events and product launches. A microsite can inherit page templates from the parent site, yet have its own theme and domain. You save time and effort by not having to create new page and component templates. Sites that are localized to user's language or geographical area can inherit templates and themes from a parent site and add its own locales to support additional languages and country-specific domains. Watch a video of this feature.

About site definitions

A site definition is responsible for assigning the following elements to a website:

  • Templates defines which page and component templates are available on the site.
  • Theme applies the visual look and feel. Themes consist of CSS, JavaScript and image variation rules.
  • Variations output content in various forms and formats.
  • i18n (internationalization) configuration allows you to serve sites in the visitor's language or geographical location.
  • Mappings identify where content for the site should be served from.
  • Domains allow branding and localization.

Default site definition

Site definitions are configured in Templating Kit > Site Definitions. The default site definition is fallback configuration for all sites and is the basis for site-specific definitions. The default configuration is explained in Site definition.

The default site definition includes:

  • Template prototype configuration in /templates/prototype.
  • Page templates available on a global level in /templates/availability.
  • Assignment of the default pop theme in /theme.
  • Variation configurations in /variations.
  • Internationalization settings in /i18n.

Best practice

Always create a specific site definition and map it to your website. Don't rely on the default site definition alone. The default is a fallback site definition. It is not mapped to any particular site in the website workspace and it does not have a domain. You should at least specify URI-to-repository mappings and domain names in your specific site definition. However, you can extend the default to save effort.

Individual site definitions

Each site requires its own site definition. The individual site definitions use the extends mechanism to extend the default definition. This means they use the default configuration and make exceptions for site-specific additions and changes.

Here are a few suggestions that you can configure in an individual site definition:

  • A site-specific template prototype that change the navigation or creates new areas.
  • Make unique page and component templates available to editors.
  • Reference a unique theme.
  • Add site-specific CSS and JavaScript.


The multisite feature uses Magnolia's core  UpdateURI2RepositoryMappings (Git) mechanism to map a site definition to a site. This means that the mechanism examines the requested URL and serves content from one of Magnolia's workspaces accordingly.

The most common use case is mapping a URI to the website workspace and serving a Web page. Content is served from the website workspace by default if the request does not contain a prefix. If a prefix such as dms is detected the requested content is served from the workspace configured in the repository property. For example, if the requested URL contains /demo-project alone, the system maps the request to the website workspace. If the request contains /demo-project/docs you could map the request to the dms workspace instead.


The handlePrefix property defines the path where content should be served from. In the demo-project website the handle points to /demo-project and in demo-features to /demo-features. These are the respective root nodes of the sites.

The handle prefix is useful when you point it to a node deeper in the site hierarchy. For example, suppose you have built a winter clothing campaign in /demo-project/campaigns/winter2012. Setting handlePrefix to this path will apply the site definition to that branch of the site only. Now content for the site will be served from the branch. In the same site definition you could configure a custom winter theme for the campaign and assign a vanity URL such as Visitors who request the vanity URL are served content from /demo-project/campaigns/winter2012, not from the site root, and they see the campaign specific theme.


The URIPrefix property is used to inject a path into a URL in order to shorten it. Shorter URLs are easier to remember, quicker to type, take less space in print ads, and are ranked more favorably by search engines than content deep down in the site hierarchy.

Suppose your marketing campaign resides deep in the site hierarchy at /demo-project/marketing/campaigns/2012/winter. First set handlePrefix to this path so that content is served from the right place. Then shorten the URL by setting URIPrefix to /winter2012. Visitors who request the URL are served content from /demo-project/marketing/campaigns/2012/winter but the URL they type is short and friendly.

The standard URI2RepositoryMapping mechanism is enhanced by the following classes in the Extended Templating Kit. They add multisite and domain support.


You can map a domain name to a site in the /domains node. Mapping domains in the CMS empowers editors as there is no need to configure a Web server. You still need to own the domain. Mapping it in Magnolia is not enough. Register a domain name with a registrar and make sure its DNS entries point to the server hosting your Magnolia instance. When visitors access the site with the domain name, content is served from the location identified by the handlePrefix.


  • context: Context path represents a web application such as magnoliaAuthor or magnoliaPublic. Context and port are needed to make links between sites work. You do not need to set these properties if you deploy to root context and default port.
  • name: Domain name such as
  • port: Port number such as 8080. Context and port are needed to make links between sites work. You do not need to set these properties if you deploy to root context and default port.
  • protocol: Protocol such as HTTPS. Default is HTTP.

The classes that provide domain mapping functionality are:

Multiple domains

You can map multiple domain names to the same site. This is useful for covering top-level domains such as .net and .org and setting localized prefixes for sites like,

Virtual URIs

Much of what can be done with domain mapping can also be done with virtual URIs. As a rule, virtual URI mapping should only be used for a small number of pages and for temporary purposes. For example, you could use a virtual URI for a Christmas campaign but once your campaign becomes a Christmas shop you should assign a site definition to it and make it a site. Defining a site opens up options such as themes and i18n support.

Request matcher rules

(warning) Magnolia 4.5.20 / Extended Templating Kit 2.0.21+ Request matcher rules can be configured in the module configuration.

ETKSiteManager matches content requests to a site in a multisite environment. Request matcher rules ensure that the correct content is served.

For complex multisite structures, you can configure precise matcher rules that take account of every possibility. Matcher classes for all properties in the site definition, and well as the site name, are provided.

The rules are resolved in the order in which they are configured, with higher configurations taking precedence. All rules are evaluated and the best-matching site served. The rules apply to all configured sites.

The default configuration in /modules/extended-templating-kit/config/rules should suffice in most environments.


  • <rule name>
    • matchers
      • <number>
        • class: Matcher class.
    • description: Describes what the configuration does.
    • multipleMatchesPossible: Whether the rule allows more than one match. When set to false, if two site definitions match, the rule is bypassed.

Matcher classes:

  • info.magnolia.module.extendedtemplatingkit.sites.matchers.SiteNameMatcher: Checks the sitename (root node of the site in Pages).

  • info.magnolia.module.extendedtemplatingkit.sites.matchers.DomainMatcher: Checks the domains configured in the site definition.
  • info.magnolia.module.extendedtemplatingkit.sites.matchers.NotEmptyUriPrefixMatcher: Checks for a URIPrefix property in the mappings node of the site definition.
  • info.magnolia.module.extendedtemplatingkit.sites.matchers.NotEmptyHandleMatcher: Checks for a handlePrefix property in the mappings node of the site definition.
  • info.magnolia.module.extendedtemplatingkit.sites.matchers.SiteHasEmptyUriPrefixMatcher: Checks for an empty URIPrefix property.


  • uri-starts-with-sitename: Site name matches. URI starts with site name: /<site-name>. Single-class rule uses SiteNameMatcher. Multiple matches not possible.
  • domain-and-uri-prefix-not-empty: Domain matches and URI prefix is not empty. Used for subsites. Dual-class rule uses DomainMatcher and NotEmptyUriPrefixMatcher. If a matching domain and URI prefix are found, the rule is bypassed. Multiple matches not possible.
  • domain-and-handle-not-empty: Domain matches and handle is not empty. Used for AdminCentral access. Dual-class rule uses DomainMatcher and NotEmptyHandleMatcher. If a matching domain and handle prefix are found, the rule is bypassed. Multiple matches not possible.
  • domain-and-site-uri-prefix-empty: Domain matches and the URI prefix is empty. Used for main site. Dual-class rule uses DomainMatcher and SiteHasEmptyUriPrefixMatcher. Multiple matches not possible.
  • uri-prefix-not-empty: URI prefix is not empty. Used for subsites that have a URI prefix. Single-class rule uses NotEmptyUriPrefixMatcher.  Multiple matches possible.
  • handle-not-empty: Handle matches. Used for AdminCentral access. Singe-class rule uses NotEmptyHandleMatcher. Multiple matches possible.

Custom matchers

You can write your own custom matcher classes to create new rules.

The custom class should extend AbstractMatcher that implements the RequestMatcher interface. The interface matches requests (domain and URI) to a site. It returns an integer, minus is false, and positive is true. The return value of @link #matches(String, String, info.magnolia.module.templatingkit.sites.Site) is used to filter the best matching request.


The first three examples demonstrate the default behavior. The last example provides a scenario where it is necessary to change it. You can replicate the examples on the demo sites. The examples assume you have mapped the domains to your system hosts file and are working locally. Domains used are, and

No site definition

  1. Set up a new site with the following structure:
    • /companyA
      • /about
      • /investors
      • /service
  2. Request

Company A site renders because it is the best-matching site. The uri-starts-with-sitename rule finds a match to the site name. No other rules are met.

(warning) Best practice is to always configure a site definition.

Domain and handle prefix

Configure a companyA site definition that extends /demo-project with:

  • /domains/companyA/name property set to
  • /mappings/website:
    • /repository set to website.
    • /handlePrefix set to /companyA.

You can now request the Company A site at The domain-and-handle-not-empty rule is met. Both the domain and handle prefix match. The pop theme is applied by extension.

Best practice

To avoid request matching conflicts give the site definition node, /domains/<node> node and the root page the same name. For example, name all three nodes companyA.

Domain and URI prefix

In the site definition created in the previous example, in /mappings/website:

  • Change /handlePrefix to /companyA/investors.
  • Set URIPrefix to /investors.

When you request you are redirected to AdminCentral because the URI prefix is no longer empty. When you request, the Investors page renders as the uri-prefix-not-empty rule is met.

URI conflict

In this example the default configuration does not serve the correct content and new rules need to be configured.

The use case could, for example, be a large corporation with a number of divisions. The corporation itself and each division has its own website and domain. Each site has a site definition that is mapped to the domain and root page (handlePrefix).

The following site structures do not result in a conflict.


Top level site

  • /corporation
    • /about
    • /investors
    • /service

Top level site

  • /division-a
    • /about
    • /products
    • /service

However when you add the subpages highlighted below the default rules no longer resolve all requests correctly because there is a URI conflict. Both sites have subpages with identical names to top-level sites.


Top-level site

  • /corporation
    • /division-a
    • /about
    • /investors
    • /service

Top-level site

  • /division-a
    • /corporation
    • /about
    • /products
    • /service

When you request the Division A page on the Corporation site, the /division-a site renders instead of the /corporation/division-a page. When you request the Corporation page on the Division A site, the /corporation site renders instead of the /division-a/corporation page. This is because there is no configured rule to take account of the situation.


Here's the configuration to correct this behavior. The configuration replaces the default uri-starts-with-sitename rule with the domain-and-sitename rule that requires both the domain name and site name to match. 

After configuring the new rule. the correct sites and subpages render.  


Internationalization support is provided by ETKI18nContentSupport. This class is configured in Configuration > /server/i18n/content and it delegates to the i18n support configured in a site definition.

A fallback i18n configuration is typically in the default site definition. Site-specific site definition can extend and override it. See Site definition > i18n for more about the default configuration. In the /demo-project-de definition the defaultLocale is changed from en to de.


The Extended Templating Kit provides three filters relevant to multisite support:


When content is published, the cache on the public instance is flushed to show the new content. This increases the load on the server and affects all sites in a multisite environment. You can configure multiple cache configurations to ensure that only cache entries that belong to the same subree (site) as the published content are flushed. See Multisite cache configuration for more.

#trackbackRdf ($trackbackUtils.getContentIdentifier($page) $page.title $trackbackUtils.getPingUrl($page))
  • No labels