Deprecated
This feature has been removed from the Web standards. Though some browsers may still support it, it is in the process of being dropped. Avoid using it and update existing code if possible; see the compatibility table at the bottom of this page to guide your decision. Be aware that this feature may cease to work at any time.
Use of zones is being deprecated
Due to an unsatisfactory user experience and the performance costs of its implementation, we are in the process of deprecating zones. Please only create a new zone if you absolutely must; generally, this should only be done to fix problems related to content which is a zone in English but not in other locales. Please drop into #mdn on IRC to ask questions about anything you read here, especially if you're considering creating a zone or turning any existing material into a zone.
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.
Once you've created a zone, as covered below, you have various special features and abilities that you can, and should, take advantage of:
There are basically two types of zone: the in-wiki zone, and the mini-site zone.
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.
Note: In-wiki zones do not typically appear in the "Zones" list on the MDN home page, since they're treated as part of the main body of MDN's documentation content.
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 /<locale>/zone/<your_zone_name>.
Note: In general, only very high-profile, special-purpose content should be moved out of the wiki hierarchy; these zones are intended primarily for setting up special-purpose promotional and/or program-related content.
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:
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:
Note: Because zones are a special-purpose construct, you will likely be asked to justify why the content should be a zone at all. Refer to What should be a zone? for insight.
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:
<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.en-US from a non-English locale, it will send users to English pages, which is probably not what you want.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.
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.
Note: It's important to keep in mind that the instructions below are suggestions. You can try to tinker further with the CSS for your zone. Just keep in mind that your changes may be reviewed by our UX and/or design teams, and will be expected to blend in well with the rest of MDN.
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.
<color>.overflow to crop it if necessary. That said, making the image too large increases page size, so that should be avoided.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.
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.
Note: Please note that because the site is actively undergoing development, anything about specific classes and styles discussed here is subject to change without notice.
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.
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.
Note: The easiest way to provide the image is to simply attach it to an appropriate page on MDN and use the resulting URL.
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.
Note: The easiest way to provide the image is to simply attach it to an appropriate page on MDN and use the resulting URL. You can choose to use the same image as you do for the landing page header image, with some scaling or cropping applied, or you can use a different image.
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.
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.
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.
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.
Draft
This section is not complete.
This section offers some notes that are worth keeping in mind when creating, working with, and using zones.