Every reference page on MDN should provide information about the specification or specifications in which that API or technology was defined. This article demonstrates what these tables look like and explains how to construct them.
These tables are similar in some respects to the compatibility tables (which should also be present on any page that has a specification table).
A specification table consists of three columns:
- The name of and link to the specification in which the technology is defined.
- The specification's status (for example, whether it's an editor's draft or a candidate recommendation).
- Any additional information that may be relevant. This can be particularly helpful when an API is defined across multiple specifications, so that you can explain briefly what parts of the API come from each one.
Each row in the table describes one specification on which the API or technology is based.
Here's an example of what a specification table looks like; this one is for the
|Document Object Model (DOM) Level 2 Events Specification||Recommendation|
|Document Object Model (DOM) Level 3 Events Specification||Working Draft|
|UI Events||Working Draft||Extend DOM3|
|Pointer Lock||Working Draft||Extend the
The table is a standard table with the CSS class
To help construct these tables in a standard format, with appropriate styling, we use KumaScript macros. There are two of these you need to know how to use.
SpecName macro is used to create the contents of the "Specification" column. It accepts three parameters:
- The name of the specification.
- An optional anchor within the specification to which to link; this lets you link to a particular section in a specification that defines multiple objects or interfaces, for example. Note that even if this parameter optional, it is strongly recommended: when the reader click on the generated link, they expect to reach the precise place in the spec where the concept is defined.
- The property or entity name to use in the tooltip; this, too, is used when linking to specific interfaces within a specification. Although this parameter is also optional, it is strongly recommended too and should be set to the name of the concept.
The names you may specify for specifications can be seen by looking at the
specList object in the macro. If the specification you want to link to is not listed in the macro, ping an admin, or the dev-mdc mailing list so that it gets added.
Spec2 macro creates and inserts a widget indicating the status of a specification into the "Status" column, given the name of a specification. Here again, if the specification you want to link to is not listed in the macro, ping an admin, or the dev-mdc mailing list so that it gets added.