Zones

A zone is a special area of MDN whose content is presented with some added user interface elements, such as a special zone navigation box and enhanced visuals in the header area of the page. This guide covers how to build and maintain zones.

Zone features

Once you've created a zone, as covered below, you have various special features and abilities that you can, and should, take advantage of:

• A colored header area with a color that uniquely identifies your zone.
• A "hero image" representing the zone in the header area.
• A zone landing page, at the base of the zone's navigation hierarchy, which presents a larger than usual banner area with the hero image in a large size and space for a short blurb describing the zone.
• A special navigation sidebar; zones may include content from anywhere on MDN in this navigation, even if they're not actually contained within the zone's direct hierarchy.
• Subpages of the zone's landing page — that is, pages actually physically located beneath the landing page — inherit the zone's color and hero image, with a smaller banner area at the top of the page.

There are basically two types of zone: the in-wiki zone, and the mini-site zone.

In-wiki zones

An in-wiki zone is a zone which takes advantage of zone functionality while remaining part of the main flow of MDN's documentation content.  These are sort of semi-zones, in that they generally don't include content from outside their own hierarchy.

An in-wiki zone allows a segment of MDN to add the additional visuals and, probably more importantly, the zone navigation sidebar, without removing the user from the main flow of MDN content.

Mini-site zones

A mini-site zone is a zone which, while edited and managed using the same interface as any wiki page on MDN, is presented outside the main flow of documentation content. In all functional respects, it supports all the standard wiki functionality provided by the Kuma platform on which MDN is built. A good example is the App Center.

When a mini-site zone is created, it is given a new URL outside the "/docs/" tree on MDN, typically at the URL https://developer.mozilla.org/<locale>/zone/<your_zone_name>.

What should be a zone?

This is an interesting question, and to be honest, the answer is likely to change over time. Zones are a new concept for MDN, and we're still learning exactly how we'll use them.

There are basically two reasons to create a zone:

1. You need to set up a mini-site for a promotional campaign or a specific product.
2. You want to create a one-stop shop, so to speak, for a topic that spans multiple technology areas.

Creating a zone

The first step is to create the content. At a minimum, you need to create the initial landing page that will become the root page for your zone. Once you have at least the root page, and possibly even your sub-content, you can then have the pages turned into a zone.

In order to turn a section of MDN into a zone requires MDN administrator privileges, so you'll need to ask an MDN administrator to do it for you. There are a few things you'll need to provide to the admin as part of your request:

• What page on MDN should be turned into the root page for the new zone. Keep in mind that all pages below it in the site's hierarchy will become part of the zone.
• Is your zone an in-wiki zone or a mini-site zone?
• You'll need to provide style information and artwork for the customization of the header area in the new zone. See Customizing the appearance for details.

De-zonifying

Because the use of zones has been deprecated, you might choose to convert an exist zone to no longer be a zone. In that case, it becomes a simple sub-section of the MDN wiki. To de-zonify:

1. Delete the zone in the admin panel. This step requires administrator privileges. You can ask an administrator to do this for you.
2. Create a subnavigation hierarchy, usually in the top-level page of the section. For example, https://developer.mozilla.org/en-US/docs/MDN contains an <h5> named "Subnav", with a hierarchical  <ol> to define the navigation hierarchy for the /MDN section of the site. This section is displayed in the sidebar area of the page, rather than inline with the article content. You could also create a navigation menu using Quicklinks.
3. Reference the subnav from other pages that you want to have use it, for example, {{IncludeSubnav("/en-US/docs/MDN")}}. Note that you should create and use a subnavigation menu specific to the locale you're working in. If you reference a subnav that exists in en-US from a non-English locale, it will send users to English pages, which is probably not what you want.

Changing the zone access policy

At this time, there's no functional support for access control for zones. This functionality is coming in the future. If you need access control for your zone, please let us know, so we can adjust the priority of that work.

Customizing the appearance

Part of what makes a zone a zone is the ability to customize its visual identity. Minimally, this means a special color and image used as the background in the header area of the zone's pages to help the user know that they're in a specific zone. It's also possible to make other basic adjustments to the appearance of the page, as long as the overall feeling of being on MDN is retained.

Basic customization

The basic, required customizations for each zone are the background color and image for the header area of the pages in the zone. When requesting that a zone be created, you'll be asked to provide these. Here are basic guidelines to what you need to provide.

• The background color should be reasonably distinctive from other zones' backgrounds, while being relevant to the topic area covered by the zone. You should specify this to the MDN administrator setting up your zone as a <color>.
• The background image is, by default, presented near the right side of the header area (or the left side in a right-to-left locale). This image may be in any Web-compatible format, although PNG is generally best. It should either blend into your specified background color or (preferably) have a transparent background. As a general rule, the background image should be about 468 pixels wide and 400 pixels tall, although the CSS on the page can be set to use overflow to crop it if necessary. That said, making the image too large increases page size, so that should be avoided.
• The image may be sent to the MDN admin with your zone creation request, or may be one that's already been uploaded to MDN as an attachment to an appropriate page.

With this information, the MDN admin team can set up the basic CSS for your zone for you. If you'd like, however, you can go a step farther and provide the CSS yourself. By following the guidelines in Additional customizations, you can experiment with other changes to the appearance of your zone.

Additional customizations

If you'd like to investigate additional customization options, take a look at the CSS/stylus template located in github. This lists all the Stylus CSS for the styles you're allowed to alter using your zone's custom CSS.

If you wish to perform additional customizations, you may do so, with one major caveat: your customizations must not be so drastic that they make the pages in the zone no longer "feel" like part of MDN.

When customizing the zone's stylesheet, it's your job to sort out from the template which styles you want to alter and to put together the CSS to do so. Once you've done so, provide that CSS to the MDN admin team, and they'll install it for you.

All zone-related content has the class zone on it.

Background colors

As mentioned previously, the first thing you're likely to customize is the background color for your zone's header area. The CSS looks something like this:

.zone #main-header, .zone .zone-article-header, .zone .zone-landing-header {
    background-color: zone-color;
}

The ID main-header refers to the site navigation area at the very top of the page. This includes the "Mozilla" cross-site navigation tab, search box, and other global navigation functionality.

The class zone-article-header represents the appearance of the header area on article pages within the zone. That is, all pages other than the base landing page within the zone will have this class on their heading area.

The class zone-landing-header is used for the header area on the zone's landing page. This is the taller heading area on the landing page, with the larger image in it.

As a general rule, you want all of these areas to have the same color; indeed, the article and landing page header colors should be the same. The only reason you might configure them differently is if they were gradients and you wanted to adjust them to have the same overall "average" color despite the different height of the space.

In short: Replace zone-color in the CSS snippet above with the <color> you've selected for your zone color.

Landing page header image

You will also want to change the image that represents your zone on the zone's landing page. This page has a larger header box to accomodate a larger image to represent your zone. The CSS looks like this:

.zone .zone-landing-header .zone-image {
    background-image: url(zone-image-url);
}

The zone-image class is used to specify and style the image for your zone's landing page header. This image should be no wider than 468 pixels, although you can override this by using additional CSS here. Simply replace zone-image-url with the URL of the image to use.

Article page header image

Additionally, you should set the image that represents your zone on its subpages. By default, this image is constrained to 200 pixels wide by 400 pixels tall, but, again, that can be overridden.

.zone .zone-article-header .zone-image {
    background-image: url(zone-image-url);
}

Just replace zone-image-url with the URL of the image to use.

Header button bottom border

The last thing you're generally advised to change is the appearance of the bottom border of the buttons in the zone header area. This is the CSS:

.zone .zone-landing-header a.button {
    box-shadow: inset 0 -1px color;
}

Here, replace color with a <color> that is very similar to your background color, but slightly darker.

Zone navigation

Zone navigation sidebar

The sidebar appearing on every page in a zone is defined in the zone's landing page content, in a section called "Subnav" (visible only when editing the page). This section may contain a manually curated list of pages or use a macro, such as ListSubpages. In the latter case you will need to force-reload (shift+refresh) the zone's landing page in order to update the sidebar.

Quicklinks

As is the case with any page on MDN, pages within zones may use the quicklinks feature. Quicklinks are a navigation box, presented in the left sidebar area, offering links the user may follow to related material. These links may be within MDN or off-site, and may be nested up to two total levels deep, using folders.

To aid in generating common types of quicklinks for zones, we have some macros you can use.

QuickLinksWithSubpages

The QuickLinksWithSubpages macro generates all of the HTML required to present a quicklinks box on the page with the links corresponding to the pages in a specified hierarchy. You can also use it with no parameters at all to present quicklinks of subpages of the current page, although this is not commonly as useful in a zone since the zone navigation will generally present this for you.

Zone style guide

Notes

This section offers some notes that are worth keeping in mind when creating, working with, and using zones.

• Every page in a zone automatically inherits the navigation sidebar provided on their zone's root page.
• If a page in a zone has a quicklinks section, the quicklinks are displayed below the zone's navigation in the sidebar. Toggling off the quicklinks makes both the quicklinks and the navigation bar disappear, allowing more room for the page content.