Markup best practice

By setting some short rules around markup, we aim to keep things looking and reading in a similar manner. Please follow them, there aren't many.

The brand dot

As part of our brand, we add a single dot (period) to the end of all text. However, there are exceptions:

• If the word ends in other punctuation, such as a question mark.
• If the word is generated as part of navigation, and would therefore break a URL string

Headings

• Keep headings short and snappy. Headings define and break-up content. Long headings are hard to digest.
• Don't use <h1> headings as they are reserved for page titles
• Use <h2> and <h3> for major sections (use your judgement on weighting)
• Use <h4>, <h5> and <h6> for minor headings
• No <code> in headings
• Never stack headings (having a heading directly after a heading in the markup).

Bad example:

## Heading
### Heading

Good example:

## Heading
Some text

### Heading
Some more text

Paragraphs

Favour longer, conjoined paragraphs over lots of short paragraphs. You don't need to break at every period. Use judgement when deciding to break into a new paragraph.

Lists

• Use ordered lists for content that has a sequential ordering to it (e.g steps in a walk-through)
• Use unordered lists in all other instances.

Try to avoid nesting lists deeper than one level (e.g a list inside a list inside a list). This can be confusing and hard to read. Instead, make use of headings and lists together to help break text into easy to digest chunks.

Good example:

* Item
* * Sub item

Bad example:

* Item
* * Sub item
* * * Sub sub item

Restricted elements

Please don't use:

• Tables
• Horizontal rules <hr>
• Breaking spaces <br>
• Inline HTML