General guidelines for all code

The following code example guidelines apply to all code, whether we are talking about HTML, CSS, JavaScript, or something else.

• Indentation, spacing, size
  • Indentation
  • Code line length
  • Code block height
• Guidelines for displaying examples
  • Size of rendered example
  • Use of images and other media
  • Use of color
  • Highlight good and bad practice examples
• Writing syntax sections on reference pages

All code should use 2 spaces for indentation, for example:

<div>
  <p>This is my paragraph.</p>
</div>

function myFunc() {
  if(thingy) {
    console.log('Yup, that worked.');
  }
}

Lines of code should be a maximum of 80 characters long (64 for interactive examples). You should break lines sensibly for the sake of readability, but not at the expense of best practices.

For example, this is not great:

let tommyCat = 'Said Tommy the Cat as he reeled back to clear whatever foreign matter may have nestled its way into his mighty throat. Many a fat alley rat had met its demise while staring point blank down the cavernous barrel of this awesome prowling machine.';

This is better, but somewhat awkward:

let tommyCat = 'Said Tommy the Cat as he reeled back to clear whatever foreign '
+ 'matter may have nestled its way into his mighty throat. Many a fat alley rat '
+ 'had met its demise while staring point blank down the cavernous barrel of '
+ 'this awesome prowling machine.';

Even better is to use a template literal:

let tommyCat = `Said Tommy the Cat as he reeled back to clear whatever foreign
  matter may have nestled its way into his mighty throat. Many a fat alley rat
  had met its demise while staring point blank down the cavernous barrel of
  this awesome prowling machine.`;

Code blocks should be as long as they need to be, but no longer. Ideally, aim for something short like 15-25 lines. If a code block is going to be a lot longer, consider just showing the most useful snippet, and link to the full example on a GitHub repo or codepen, say.

The MDN main content pane is about 700px wide on desktop, so embedded MDN examples must look OK at that width (set the width of embedded examples at 100%).

For height, we'd recommend keeping the rendered example at below 700px in height if at all possible, for maximum onscreen legibility.

You should also think about making your examples responsive to some degree, so they are also useful on mobile devices.

Sometimes you'll want to include images or other media in an example. If you do:

• Make sure their license allows you to use them. Try to use media that has a very permissive license such as CC0, or at least one that is compatible with our general content license — Creative Commons Attribution-ShareAlike license (CC-BY-SA).
• For images, run them through https://tinypng.com or https://imageoptim.com, to reduce the page weight of the examples.
• For SVG, run the code through SVGOMG, and ensure that the SVG file has an empty line at the end of the file.
• When displaying icons on a page (e.g. via background-image), use icons from the mdn-dinocons repository, where appropriate, and try to match their style in other cases.

Lower case for hex, can use keywords for shades and primary colors (e.g. black, white, red), use more complex schemes only when needed (e.g. to include transparency)

Prefer to use keywords for primary and other "basic" colors, for example:

color: black;
color: white;
color: red;

Use rgb() for more complex colors (including semi-transparent ones):

color: rgb(0, 0, 0, 0.5);
color: rgb(248, 242, 230);

If you have to use hex colors, then use lower-case:

color: #058ed9;
color: #a39a92;

and use the short form where relevant:

color: #ff0;
color: #fff;

The sass/vars/_color-palette.scss file in the mdn-minimalist repository has a set of useful colors that complement the overall MDN design.

As you will notice from looking around these guidelines, the code blocks that are supposed to be good practice examples are highlighted with a smiley face in green, and the code blocks that are supposed to be bad practice examples are highlighted with a sad face in red.

To do this, you first use the MDN editor controls to put your code block in a <pre> block and give it appropriate syntax highlighting. The source of the code will look something like this:

function myFunc() {
  console.log('Hello!');
};</pre>

To make it into a good example, you insert example-good just before the closing quote of the class attribute:

<pre class="brush: js example-good">
  ...

To make it into a bad example, you insert example-bad just before the closing quote of the class attribute:

<pre class="brush: js example-bad">
  ...

We would like to encourage you to use these. You don't need to use these everywhere — only when you are specifically calling out good and bad practices in your code.

MDN reference pages include Syntax sections that show unambiguously what the syntax of a feature can/should be, for example a JavaScript method, CSS property, HTML element, etc. Guidelines for writing these are given on the Syntax sections document.