Heading level 1

Bulleted lists

Use a bulleted list to present a series of similar items that don't have a logical ordering.

There are several different ways to identify bulleted lists in Markdown, but we'll use "-" throughout for consistency.

• This is the first item in the bulleted list.
• This is the second item. As before, leave a blank line between each item in the list, and start a new line for each sentence in a single list item.
• This is the third item in the list.

Here's the Markdown for the list above.

- This is the first item in the bulleted list.

- This is the second item.
As before, leave a blank line between each item in the list, and start a new line for each sentence in a single list item.

- This is the third item in the list.

Character formatting

Bold

There are several different ways to denote a bold font in Markdown. For consistency, we'll use two consecutive asterisks ("**"), so this text is bold.

Note that, in the Markdown, the first mention of the asterisks needed them to be escaped by prefixing with a backslash ("\"), to stop them being treated as an instruction to bold the text that follows. Note that the backslash itself in the previous sentence also needed to be escaped for the same reason.

Here's the Markdown for the text above.

There are several different ways to denote a bold font in Markdown.
For consistency, we'll use two consecutive asterisks ("\*\*"), so this **text is bold**.

Note that, in the Markdown, the first mention of the asterisks needed them to be _escaped_ by prefixing with a backslash ("\\"), to stop them being treated as an instruction to bold the text that follows.
Note that the backslash itself in the previous sentence also needed to be escaped for the same reason.

Use a bold font for:

• file and folder names, for example "Edit the config.json file".
• other technical terms that you want to differentiate from the surrounding text, for example "We use SHA512withRSA to calculate the payload digest".
• UI text, for example "Click Create Webhook ."
• (sparingly) in other places where you want to add emphasis, for example "You must verify state matches the state you sent us".

Italics

There are several different ways to denote an italics font in Markdown. For consistency, we'll use the underscore character "(_)", so this text is in italics. Again, we had to escape the first underscore n the previous sentence to stop it being treated as an instruction to use italics for what follows.

Here's the Markdown for the text above.

There are several different ways to denote an italics font in Markdown.
For consistency, we'll use the underscore character "(\_)", so this _text is in italics_.
Again, we had to escape the first underscore n the previous sentence to stop it being treated as an instruction to use italics for what follows.

In general, you'll rarely need to use italics in technical writing. I may decide to use it as a standard for placeholder text (or I may not): watch this space. It's also harder for dyslexics to read, so isn't generally recommended for accessibility reasons.

You may need to use it to highlight the first mention of an unfamiliar term that you are about to define in the words immediately following it. For example, I did this when I first mentioned escaped in the section on bolding above.

Code

When to use code styling

Use a code style for:

• actual code
• other references to code items, where you are using the name used by the code
• API endpoint names

Do not use a code style if you are referring to a real-world concept, rather than the code item itself.

Inline code

Here's a variable called inline-code.

Here's the Markdown for the sentence above.

Here's a variable called `inline-code`.

Code blocks

Here's a code block. In principle, if you state the language in the code block delimiter, as in this example, the code block should include syntax highlighting when it is rendered. But I've not managed to get this working yet.

{
    "access_token": "eyJhbGciOiJQUzI1NiIsInppcCI6IkdaSVAifQ.H4sIAAQ-_pT1TALVKOt8.uLjFJikw--DDv3Pf",
    "refresh_token": "De2yfE70KcoFkaEQvVW236s2UVaVexzKGUjHYAG2OGutlO5GLJiSN0rv2P8dean1",
    "token_type": "Bearer",
    "expires_in": 3600,
    "scope": "account:read balance:read card-control:edit card:read transaction:read"
}

Tables

GFM supports the pipe ("|") table syntax, where each cell is separated from the next with a "|" symbol. The body rows are separated from the header rows with a row that looks like this in Markdown.

| ---- | ---- | ---- |

There's one section for each column in the table.

In theory, you should be able to use | :--- | in the header row for left justification of that column, | :---: | for centre justification and | ---: | for right justification. But that seems to work for the body rows, but not the header rows!

Also, in GFM you must ensure there is a blank line before the start of the table. Otherwise it won't render correctly. So here's a table.

Images

Image format and resolution

TODO Still need some notes about how to generate the image, where to store the source file (and the output file, if different), and the output format to choose. All this will depend on the choice of tool.

Image example

Here's an image.

TODO The image below doesn't exist at present - find something suitable.

Don't code images directly in the body of the text. Instead, define an image ID in a separate section at the bottom of your content, and reference the image ID where it's required. This makes the text cleaner, and it's easier to locate and update the location of images if they change.

So here's how the image above looks in Markdown.

![Image showing a word cloud][word-cloud-image]

The alt text is Image showing a word cloud, and the image ID is word-cloud-image.

And here's the image ID definition of word-cloud-image at the bottom of the content.

[word-cloud-image]: ./images/wordcloud.png "Example word cloud"

The image title is Example word cloud. The image URL is relative to the location of the Markdown file that references it.

Resizing Images

If you need to resize the image in the output, then unfortunately, you can't use the image ID format above. You'll have to use the <img> HTML tag.

So here's the word cloud image, resized to 200px wide.

And here's how this looks in Markdown. Don't forget to include the image title and the alt text.

<img src="./images/wordcloud.png"
     width="200px"
     title="Example word cloud"
     alt="Image showing a word cloud"/>

Links

About links

Each link can potentially break the reader's train of thought, so use links sparingly, and only where they add value.

Choose the link text and the context around the link text carefully. Make sure it's clear what kind of information the reader will find if they click the link. Then they can easily decide whether it's worth breaking their current reading flow to follow the link.

Make sure that if the reader follows the link, the heading text they find matches what the link text promised them. For example, don't promise the reader a link telling them how to install and configure the sunshine widget if the linked page is simply called Weather.

Don't code link locations directly in the body of the text. Define a link ID in a separate section at the bottom of your content, and reference the link ID wherever it's required. This makes the text cleaner, and it's easier to locate and update links if they change.

Here's a link to Google as an example.

Here's how this sentence looks in Markdown.

Here's a [link to Google][link-to-google] as an example.

The link text the reader sees is link to Google and the link ID is link-to-google.

The corresponding link ID definition at the end of the content looks like

[link-to-google]: <https://www.google.co.uk/>

### <span id="bulleted-lists">Bulleted lists</span>

Here's an example of a internal link to the section about [bulleted lists in Markdown][bulleted-lists].

<div role="alert" class="alert alert-warning"><span class="bold">Note</span>
  <p>
    <span class="bold">
      Here's your warning text. 
      It can have more than one sentence in it
    </span>
  </p>
</div>

<!-- This is a comment about the content -->