ingredient-spec.md

JavaScript reference docs structure specification

This document describes the structure we want to require for JavaScript reference documentation.

Recipes and ingredients overview

It is expected that pages documenting different sorts of thing will need to contain different elements. For example, the page for the JavaScript BigInt class will want to contain lists of links to its members, while the page for the JavaScript BigInt.asUintN() static method will want to contain a section describing the method syntax.

To reflect this, a "recipe" is a short YAML file that describes at a high level the elements that a particular type of page is expected to have. A recipe provides a list of elements, that are expected to appear in the page in the order given. So for each distinct type of page, we define a single recipe.

Each element is called an "ingredient". Ingredients are often shared across recipes. So for example we have an ingredient called data.browser_compatibility, which most recipes will contain. Each ingredient may have particular requirements about how it is represented in the page: for example, to satisfy the data.browser_compatibility ingredient a page must include the {{Compat}} KumaScript macro.

So at a high level, compliance to a recipe means:

the items in the page must correspond to the ingredients listed in the recipe, in the correct order, and each item must satisfy the particular requirements for its ingredient.

JavaScript recipes

We've defined the following recipes for the JS docs:

• javascript-class
• javascript-namespace
• javascript-constructor
• javascript-method
• javascript-property
• javascript-error
• javascript-language-feature

JavaScript recipe ingredients

In total these recipes use the following ingredients:

prose ingredients:

• prose.short_description
• prose.description?
• prose.see_also
• prose.syntax
• prose.message
• prose.error_type
• prose.what_went_wrong
• prose.*

data ingredients:

• data.interactive_example?
• data.class_constructor
• data.constructor_properties?
• data.static_properties?
• data.static_methods?
• data.instance_properties?
• data.instance_methods?
• data.examples
• data.specifications
• data.browser_compatibility

All ingredients except two are demarcated in the page using an <h2> heading. The exceptions are prose.short_description and data.interactive_example.

Prose ingredients

With three exceptions, all prose ingredients impose the same requirement on the page: it must have an <h2> section whose ID attribute maps to the named section. The mapping is simply that prose. is removed, and the first letter is capitalized:

prose.syntax      ->    Syntax
prose.see_also    ->    See_also

The exceptions are prose.short_description, prose.description?, and prose.*.

prose.short_description

This ingredient isn't demarcated by an <h2> at all. To satisfy the ingredient, a page must:

• contain a <p> element
• that is not a note or a warning
• before the interactive example or the first <h2>, whichever comes first

prose.description?

This is an optional prose ingredient. To satisfy the ingredient, if the page contains an h2#Description, then it must appear in the place specified by the recipe.

prose.*

This ingredient enables writers to include extra sections, but ensuring that they always appear in the same place in the page. To satisfy this ingredient: if the page contains any <h2> headings that are not expected by the recipe, then they must appear at the point in the page that the prose.* ingredient is listed in the recipe.

Data ingredients

Data ingredients typically impose more detailed requirements on pages than prose ingredients.

data.interactive_example?

This is an optional data ingredient. To satisfy the ingredient, if the page contains a call to the {{EmbedInteractiveExample}} macro, then the call must appear in the place specified by the recipe.

data.class_constructor

To satisfy this ingredient, a page must meet the following requirements:

• A section demarcated by H2#Constructor that contains only a <dl> element.
• The <dl> must contain a single <dt><dd> pair.
• The <dt> must contain either:
  • only a single <code> element, that contains only a single <a> element
  • only a call to the {{jsxref}} macro.

data.constructor_properties?

This is an optional ingredient. If a page contains a section demarcated by H2#Constructor_properties, then it must meet the following requirements:

• Must contain only a <dl> element.
• The <dl> must contain one or more <dt><dd> pairs.
• The <dt> must contain either:
  • only a single <code> element, that contains only a single <a> element
  • only a call to the {{jsxref}} macro.
• <dt><dd> pairs must be ordered by the alphabetical order of the <dt><code><a> text content, or by the display name given in the {{jsxref}} macro call.

data.static_properties?

This is an optional ingredient. It's just the same as data.constructor_properties?, except the section is demarcated by H2#Static_properties.

data.static_methods?

This is an optional ingredient. It's just the same as data.constructor_properties?, except the section is demarcated by H2#Static_methods.

data.instance_properties?

This is an optional ingredient. It's just the same as data.constructor_properties?, except the section is demarcated by H2#Instance_properties.

data.instance_methods?

This is an optional ingredient. It's just the same as data.constructor_properties?, except the section is demarcated by H2#Instance_methods.

data.examples

To satisfy this ingredient a page must have a section demarcated by H2#Examples. It must contain one or more sections demarcated by an H3. Each of these sections represents a single example.

Each of these examples may include "code sections". These are marked up as follows:

• HTML code section: <pre class="brush: html language-html"><code class=" language-html">
• CSS code section: <pre class="brush: css language-css"><code class=" language-css">
• JavaScript code section: <pre class="brush: js language-js"><code class=" language-js">

Examples must follow some rules about which sections may appear and how they are ordered:

• An example may contain zero or one of each type of section.
• If an example includes a JavaScript code section, it must be the last element in the section.
• If an example includes a CSS code section, it may only be followed by a JavaScript section.
• If an example includes an HTML code section, it may only be followed by a CSS section.

Another way to put this is: each example is structured like:

unstructured prose
optional HTML section
optional CSS section
optional JavaScript section

data.specifications

To satisfy this ingredient a page must have a section demarcated by H2#Specifications. It must contain either a call to the {{SpecName}} macro, or a text node containing the text "Not part of any standard".

data.browser_compatibility

To satisfy this ingredient a page must have a section demarcated by H2#browser_compatibility. It must contain a call to the {{Compat}} macro.