Skip to main content

Contributing overview

Last updated: 2022-05-23

Technical contributors

If you are familiar with Git, please feel free to make a pull request to the Handbook GitHub repo. Make sure you read the Technical guidelines section below for info on linting, markdown etc.

Non-technical contributors

If you are not familiar with Git and want to contribute, get in touch on the #handbook-contribute Slack channel where you'll find friendly helpers to guide you through the process.

Technical Guidelines

Frontmatter

Markdown files start with a section called "frontmatter" which at a minimum specifies the document title. All other fields are optional. Frontmatter is delineated with three dashes before and after.

---
title: Roles overview
sidebar_label: Overview
slug: overview
public: true
---
FieldNotes
titleThe title as displayed at the top of the page. Also the label which appears in the navigation sidebar, unless sidebar_label is specified.
sidebar_labelOptional label to show in the sidebar if the title should not be used.
slugOptional URL part for this page. Defaults to the filename without the .md extension.
publicOptional. Defaults to false if not specified. This should be true to make the page visible to anonymous users; false if it should only be visible to logged-in users.

The items which appear in the navigation sidebar are configured by editing the sidebars.js file. Look for the block which starts with:

const fullSidebar =

The format is relatively straightforward, but since this is code it does need to be precisely correct, and small inconsistencies can lead to errors.

The overall structure is:

const fullSidebar = {
Handbook: [
... list of items ...
]
};

Each item may be a "container" or a link to a specific page, for example:

{                                          <- Start of container item
'Home': [ <- Label and start of list
'home/home', <- Link to page
'home/about', <- Link to page
'home/contributing/contributing', <- Link to page
],
}

Note that each page must be specified by giving the location of the file and removing the .md suffix.

If you don't need to specify the order of pages within a section, you can let them be automatically discovered. For example, this finds all items in the content/career/roles folder and all sub-folders, and sorts them alphabetically:

    {
"Roles": findDocs(`career/roles`)
}

Editing content locally on your machine

Those familiar with the process can clone the repository to edit content locally on their machine. The README has instructions on building and running the site locally.

Visual Studio code is recommended, with the Markdown All in One plugin installed. Please read through the notes above regarding specific conventions which apply to handbook content.

Markdown Linting

Please enable markdown linting on this project by running yarn install. Linting is performed in two ways:

The first is the VScode Extension markdownlint that will indicate to you that you've violated a linting rule when editing a document. You will see a squiggly yellow line under the offending line.

Example of VSCode markdownlint extension

The second is a pre-hook commit which is run via Husky. When you commit changes, the hook will scan the markdown files in the repository to check if you've violated any of the rules. You can view the rules in .markdownlint.json.

Markdown guide

In addition to these notes, you may wish to refer to the Markdown Cheat Sheet.

Headings

Section headings are created by starting a line with a number of hash-marks. On Mac keyboards, the # symbol can be entered with Option + 3 or Alt + 3 (i.e. hold the Option or Alt key and press 3).

caution

Top-level headings should use ## ('H2') rather than # ('H1') as otherwise the page will include multiple headings at the same level as the page title. This is bad practice and does not work well with the table of contents, which only recognises ## and ### (H2 and H3)-level headings.

Emphasis

Text is made bold by surrounding it in double asterisk marks: **this is bold**.

Text is made italic by surrounding it in single underscore marks: _this is italic_. The _ symbol can by entered with Shift + - (i.e. hold Shift and press the - key).

Lists

Where the order of items in a list is not significant, use bullet points:

MarkdownHow it appears in the Handbook
A bullet list:

- Item one
- Item two
- A sub-item
- Item three

A bullet list:

  • Item one
  • Item two
    • A sub-item
  • Item three

Where order is important use a numbered list. It is easiest to use 1. for every item; these are automatically converted into a sequence of numbers starting at 1. Using 1 is a convention which makes it easier to add, remove and reorder items, but in fact it does not matter which number you use for each point. Specifically, there is no way to start a list at anything other than 1 or to reverse the ordering.

MarkdownHow it appears in the Handbook
A numbered list:

1. Item one
1. Item two
1. A numbered sub-item
1. Item three
- A bullet sub-item

A numbered list:

  1. Item one
  2. Item two
    1. A numbered sub-item
  3. Item three
    • A bullet sub-item

Links to sections within the same document are created with:

[Link text](#section-id)`

The ID for a section is formed by converting all letters to lower case and replacing spaces with dashes (-). For example, to link to a section with the heading "ISO compliance", use [ISO](#iso-compliance). The link text does need to be the same as the section title, as in this example.

Links to other documents are created with:

[Link text](filename.md)

Here, filename.md may refer to a file in the same folder or a different folder. For example, to create a link in content/people/career/core-skills to content/people/roles/index use [roles](roles/index). The "file name" here includes the folder name "roles", which is alongside the file from which the link is being made. To create a link to a file which is not in a sub-folder, specify the full location, starting with a /. For example, in content/people/career/roles/overview create a link as [core skills](/people/career/core-skills). Note that in all cases the link refers to the filename, which is converted into the correct URL when the site is deployed.

You can combine these to link directly to a section of another document. For example, [colours](../../brand/assets#icons).

Links to external resources are created as:

[Link text](https://example.com)

Images are embedded in a way which looks like a link preceded by an exclamation mark:

![Alt text](my-image.jpg)

The alt text is used by screen readers or similar. Images should be placed inside the content/ folder to ensure caching rules are properly applied.

Tables

Tables are created with Markdown like this:

| Heading 1 | Heading 2 |
|-|-|
| Row 1, column 1 | Row 1, column 2 |
| Row 2, column 1 | Row 2, column 2 |

Which displays this in the Handbook:

Heading 1Heading 2
Row 1, column 1Row 1, column 2
Row 2, column 1Row 2, column 2
tip

Markdown tables can themselves contain simple Markdown such as **bold** and _italic_, but multi-line markdown content such as lists are not supported. To create tables which contain Markdown lists you must hand-craft HTML tables using <table> and related elements.

Callouts

The handbook supports extended Markdown syntax for "admonition" callout boxes:

MarkdownDisplays as
:::note Note title
This is a note.
:::
Note title

This is a note.

:::tip Tip title
This is a tip.
:::
Tip title

This is a tip.

:::info Info title
This is an information box.
:::
Info title

This is an information box.

:::caution Caution title
This is a caution.
:::
Caution title

This is a caution.

:::warning Warning title
This is a warning.
:::
Warning title

This is a warning.