Syntax sections

API reference syntax

Syntax sections for API reference pages are written manually, and they different depending on what page type they are included in. However, all have some things in common — in each case the section is titled "Syntax", and included at the top of the reference page, just below the introductory material.

In addition, each syntax section starts with a "code" block showing the feature's exact syntax, styled using the "Syntax Box" block style:

A syntax block example

This looks similar to JavaScript, but is written in a format called formal syntax — there are some differences that you'll become familiar with as you look at more examples. Take the first example in the next section — the parameter in brackets is an optional parameter.

Constructors and methods

Syntax block

Start with a syntax block, like this (see the IntersectionObserver constructor page):

var observer = new IntersectionObserver(callback[, options]);

or this (see WindowOrWorkerGlobalScope.fetch):

Promise<Response> fetch(input[, init]);

Sometimes you'll have to include multiple lines, because the method can be used in different forms. For example, see this example (CanvasRenderingContext2D.drawImage):

void ctx.drawImage(image, dx, dy);
void ctx.drawImage(image, dx, dy, dWidth, dHeight);
void ctx.drawImage(image, sx, sy, sWidth, sHeight, dx, dy, dWidth, dHeight);

The aim is to make the syntax block as pure and unambiguous as definition of the feature's syntax as possible — don't include any irrelevant syntax. For example, you will see this syntax form used to describe promises in many places on the site:

caches.match(request, options).then(function(response) {
  // Do something with the response
});

But this version is much more concise, and doesn't include the superfluous Promise.prototype.then() method call:

Promise<Response> caches.match(request, options);

Parameters section

Next, include a "Parameters" subsection, which explains what each parameter should be, in a description list. Parameters that are objects containing multiple members can include a nested description list, which itself includes an explanation of what each member should be. Optional parameters should be marked with an {{optional_inline}} macro call next to their name in the description term.

Note: If the feature does not take any parameters, you don't need to include a "Parameters" section, but you can if you wish include it with content of "None".

Return value section

Next, include a "Return value" subsection, which explains what the return value of the constructor or method is, even if it is Void. See the above links for examples.

Exceptions section

Finally, include an "Exceptions" subsection, which explains what exceptions can be thrown if a problem is encountered when invoking the constructor/method. This could be because a parameter name has been misspelt or it has been given a value of the wrong datatype, because there is problem with the environment it is being invoked in (e.g. trying to run a secure context-only feature in a non-secure context), or some other reason.

The exception names and explanations should be included in a description list.

Note: If no exceptions can be raised on the feature, you don't need to include an "Exceptions" section, but you can if you wish include it with content of "None".

Properties

Syntax block

Start with a syntax block, like this (see IntersectionObserver.root):

var root = IntersectionObserver.root;

For a non-read-only property, it is a good idea to include two lines, which show getting and setting the property (see AudioParam.value):

gainNode.gain.value;
gainNode.gain.value = 0;

Value section

Below the syntax block you need to include a "Value" subsection, which cotains a explanation of the property's value — both its data type and what its purpose is. 

Event handlers

Evet handler properties are still properties are still properties, but they have some differences in their syntax sections.

Syntax block

Start with a syntax block, like this (see Window.onvrdisplaypresentchange):

window.onvrdisplaypresentchange = functionRef;

And that's it — event handler properties are always settable, and always contain a function, therefore no more information is needed.
 

JavaScript reference syntax

JavaScript built-in object reference pages follow the same basic rules as API reference pages. There are a few differences that you might observe:

  • For built-in objects with a single constructor, the constructor syntax is often included on the object landing page. See Date for example. You'll notice that static methods (those that exist on the Date object itself) are listed under "Methods", whereas instance methods are listed under "Date.prototype methods".
  • You'll also notice that methods that have no parameters/exceptions are more likely to have those subsections not included at all on JavaScript rerefence pages. See Date.getDate() and Date.now() for examples.

CSS reference syntax

Properties

CSS property reference pages include a "Syntax" section, which used to be found at the top of the page but is increasingly commonly found below a section containing a block of code showing typical usage of the feature, plus a live example to illustrate what the feature does (see animation for example).

Note: We do this because CSS formal syntax is complex, not used by many of the MDN readership, and offputting for beginners. Real syntax and examples are more useful to the majority of people.

Inside the syntax section you'll find the following contents.

Optional explanation text

Some CSS properties are self-explanatory and don't really need extra explanation (for example color). Some on the other hand are more complex and need explanation on syntax order, including multiple values, etc. (see animation). In such cases you can include extra explanation before any of the subsections.

Values section

Next, you should include a "Values" section — this contains a description list explaining the CSS value types that make up the value of the property. Each value type should be wrapped in angle brackets and linked to the MDN reference page covering that value type if a page exists for it. For example, see the border property reference — this reference three value types, only one of which is linked (<color>).

Formal syntax

the last section, "Formal syntax", is automatically generated from the data included in the MDN data repo's CSS directory. You just need to include a {{csssyntax}} macro call below the title, and it will take care of the rest.

The only complication arises from making sure the data you need is present. The properties.json file needs to contain an entry for the property you are documenting, and the types.json file needs to contain an entry for all of the value types used in the property's value.

You need to do this by forking the MDN data repo, cloning your fork locally, making the changes in a new branch, then submitting a pull request against the upstream repo. You can find more details about using Git here.

Selectors

The "Syntax" section of selector reference pages is much simpler than that of property pages. It contains one block styled using the "Syntax Box" style, which shows the basic syntax of the selector, whether it is just a simple keyword (e.g. :hover), or a more complex function value that takes a parameter (e.g. :not). Sometimes the parameter is explained in a further entry inside the syntax block (see :nth-last-of-type for an example).

This block is automatically generated from the data included in the MDN data repo's CSS directory. You just need to include a {{csssyntax}} macro call below the title, and it will take care of the rest.

The only complication arises from making sure the data you need is present. The selectors.json file needs to contain an entry for the selector you are documenting.

You need to do this by forking the MDN data repo, cloning your fork locally, making the changes in a new branch, then submitting a pull request against the upstream repo. You can find more details about using Git here.

HTML reference syntax

HTML reference pages don't have "Syntax" sections — the syntax is always just the element name surrounded by angle brackets, so it isn't needed. the main thing you need to know about HTML elements is what attributes they take and what their values can be, and this is covered in a separate "Attributes" section. See <ol> and <video> for examples.

HTTP reference syntax

HTTP reference syntax is all manually created, and differs depending on what type of HTTP feature you are documenting.

HTTP headers/Content-Security-Policy

HTTP header syntax (and Content-Security-Policy) is documented in two separate sections on the page — "Syntax" and "Directives".

Syntax section

The "Syntax" section shows what a header's syntax will look like, using a syntax block styled using the "Syntax Box" style, including formal syntax to show exactly what directives can be included in the value, in what order, etc. For example, the If-None-Match header's syntax block looks like this:

If-None-Match: <etag_value>
If-None-Match: <etag_value>, <etag_value>, …
If-None-Match: *

Some headers will have separate request directive, response directive, and extension syntax. If available, these must be incuded in separate syntax blocks, each under its own subsection. See Cache-Control for an example.

Directive section

The "Directive" section contains a description list containing the names and descriptions of all the directives that can appear inside the syntax.

HTTP request methods

Request method syntax is really simple, just containing a syntax block styled using the "Syntax Box" style that shows how the method syntax is structured. The syntax for the GET method looks like this:

GET /index.html

HTTP response status codes

Again, the syntax for HTTP repsonse status codes is really simple — a syntax block including the code and name. For example:

404 Not Found

SVG reference syntax

SVG elements

SVG element syntax sections are non-existant — just like HTML element syntax sections. Each SVG element reference page just includes a list of the attributes that can apply to that element. See <feTile> for example.

SVG attributes

SVG sttribute reference pages also do not include syntax sections.

Document Tags and Contributors

 Contributors to this page: chrisdavidmills
 Last updated by: chrisdavidmills,