Skip to main content

Design styleguide

Content not complete

Sometimes it's necessary to flag a page. This should be used sparingly and is implemented using a caution admonition with a descriptive title at the top of the page.

The design styleguide provides a quick reference of all available content styles so that design changes can be assessed quickly and easily.

For guidance on using the available content styles, see the Contributing overview.

Headings

Headings are a fundamental element of good content structure, assisting the reader to scan content and find what they need. Heading levels two and three are automatically added to the context menu on the right.

Heading level two

Heading level three

Heading level four

Heading level five
Heading level six

All headings have an automatically generated anchor matching the text of the heading, enabling the heading to be linked to. A specific anchor can be defined by appending a custom ID using the format {#custom-id}:

### Heading level three {#my-custom-anchor-link}

Text styles

This is a basic paragraph. You'll need to see the paragraph spanning multiple lines to get a sense of the line height. Standard text can also include emphasised text or bold text, all achieved using appropriate Markdown styling. A link can of course also be included within a basic paragraph.

Text can also be presented as a blockquote, which can include a link if required.

Lists

Ordered and unordered lists are supported and are easy to implement.

Ordered list

An ordered list is a numbered list that can also support numbered sub-lists. In Markdown, you can add each list item with the 1. prefix, and it will be rendered with the correct number for its position.

  1. Aenean eu leo quam.
  2. Pellentesque ornare sem lacinia quam venenatis vestibulum.
    1. This list is a child of the original list.
      1. This list is a grandchild of the original list.
  3. Nulla vitae elit libero, a pharetra augue.
  4. Cras justo odio, dapibus ac facilisis in, egestas eget quam. Donec sed odio dui.

Unordered list

An unordered list is a bulleted list that can also support bulleted sub-lists.

  • Aenean eu leo quam.
  • Pellentesque ornare sem lacinia quam venenatis vestibulum.
    • This list is a child of the original list.
      • This list is a grandchild of the original list.
  • Nulla vitae elit libero, a pharetra augue.
  • Cras justo odio, dapibus ac facilisis in, egestas eget quam. Donec sed odio dui.

Details

The details block is typically used to show extended content, with meaningful, clickable text to expand the extra information. However, it is not supported in Markdown and therefore must be implemented using HTML.

Be familiar with relevant terms and other related information
  • Information that is helpful in context but not so important that it breaks the page flow
  • Content that might be new to some people but known to others
  • Standard terms such as this, that or the other
  • References with key meanings such as them and those things
  • Other contextual material that is helpful but not necessarily critical
  • Remember that a link can be included in a details block

Try to avoid links within the header of a details block as they're not obvious and create a slightly conflicting interaction:

You can have a link within a details heading

But it creates a slightly inferior UX and can only be implemented as HTML!

Code

As a technical consultancy, we may need to show code examples or snippets on Handbook pages. Both inline code and blocks of code are supported, though only code blocks present the reader with a 'click to copy' feature:

<ul>
<li>This code snippet shows an HTML list.</li>
<li>It includes some <strong>inline elements</span>.</li>
</ul>

For syntax highlighting, a single language immediately after the first three backticks:

```html, js, json, etc

Blockquote

This is the content within a blockquote.

It is generally used to quote text that has come from another source.

Callout styles

Callout boxes (aka 'Admonitions') are typically used to highlight short content snippets amongst lengthier content.

Maecenas faucibus mollis interdum. Cras mattis consectetur purus sit amet fermentum. Maecenas faucibus mollis interdum.

Note title

This is a note callout. Cras justo odio, dapibus ac facilisis in, egestas eget quam.

Maecenas faucibus mollis interdum. Lorem ipsum dolor sit amet, consectetur adipiscing elit. Maecenas sed diam eget risus varius blandit sit amet non magna.

Tip title

This is a tip callout. Vestibulum id ligula porta felis euismod semper.

Donec sed odio dui. Donec sed odio dui. Etiam porta sem malesuada magna mollis euismod. Nulla vitae elit libero, a pharetra augue. Curabitur blandit tempus porttitor.

Info title

This is an info callout. Donec sed odio dui. Lorem ipsum dolor sit amet, consectetur adipiscing elit.

Donec sed odio dui. Vivamus sagittis lacus vel augue laoreet rutrum faucibus dolor auctor. Vestibulum id ligula porta felis euismod semper.

Caution title

This is a caution callout. Praesent commodo cursus magna, vel scelerisque nisl consectetur et.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum id ligula porta felis euismod semper. Nulla vitae elit libero, a pharetra augue.

Legacy content

The content on this page has been migrated from an older system and is due to be rewritten.

Lorem ipsum dolor sit amet, consectetur adipiscing elit. Vestibulum id ligula porta felis euismod semper. Nulla vitae elit libero, a pharetra augue.

Warning title

This is a warning callout. Donec ullamcorper nulla non metus auctor fringilla.

Tables

Tables can be fiddly to edit in Markdown but are a good method for presenting structured information.

ComponentValueNotes
ThisHighAll styles of text are supported in a table, including links.
ThatMediumNulla vitae elit libero, a pharetra augue. Curabitur blandit tempus porttitor.
The otherLowDuis mollis, est non commodo luctus, nisi erat porttitor ligula, eget lacinia odio sem nec elit. Praesent commodo cursus magna, vel scelerisque nisl consectetur et.