This page provides guidance when working with the MD format.

General formatting

Italics - use single asterisks:

*this is in italics*

Bold - use double asterisks:

**this is in bold**

Monospace - use single backticks:

the `--force` option may help

Section headers

There are five section headers:

# H1

## H2

### H3

#### H4

##### H5

Inline commands

For commands or utilities that are mentioned in a sentence use monospace:

You can type the `juju status` command to get an overview of the model.

The `openstack` client is the preferred tool.

Linking to an external site

The [OpenStack Charms Deployment Guide][cdg] ...


... in the [OpenStack Charm Guide][cg] ...


See bug [LP #1862392][lp-bug-1862392] ...

<bottom of page>

<!-- LINKS -->


Linking to a header within the current page

See section [Availability zones][anchor-az]...


## Availability zones

<bottom of page>

<!-- LINKS -->

[anchor-az]: #availability-zones


Markdown itself does not have admonishment types as such. Implement an equivalent RST admonishment as a Markdown quote:




to provide auxiliary information


to inform


to accentuate


to draw special attention to


to warn about potential breakage or data loss


> **<type>**: text goes here. text goes here. text goes here. text goes here
  maintain the alignment.

The text is left-aligned with the asterisks.


> **Note**: The 'ceph-rbd-mirror' charm addresses only one specific element
  in datacentre redundancy.

Code blocks

Console input

Indent four spaces:

The following command shows the relations:

    juju status --relations

Console output

Indent four spaces:

Sample output of the last command is:

    Name              Version               Rev    Tracking        Publisher    Notes
    charm             2.8.2                 609    latest/stable   canonical✓   classic
    charmcraft        1.4.0                 761    latest/stable   canonical✓   classic

Code snippet

Use syntax highlighting for code snippets/scripts using backticks and a language type:

  • python

  • bash

  • yaml

Do not use the bash type for simple command invocations.


This bit of Python will do the trick:

   import random

   def flip():
       if random.randint(0,1) == 0:
           return "heads"
           return "tails"
         def anagram(first, second):
          return Counter(first) == Counter(second)

Use your prerogative for indentation.

Miscellaneous file contents

Indent file contents with four spaces:

The contents of file ``/etc/ec2_version`` is:

    Ubuntu 20.04.1 LTS (Focal)


Add a blank line between each item if any list items are multi-lined.

Unordered list

* First item. Align any word-wrapped lines
  like this.

* Second item

Nested unordered list

Indent nested items with four spaces:

* First item
    * Nested item

Ordered list

1. First item
1. Second item

Nested ordered list

Indent nested items with four spaces:

1. First item
    1. Nested item


A regular image:



<bottom of page>

<!-- LINKS -->

[image]: path to image

An image as hyperlink:



<bottom of page>

<!-- LINKS -->

[image]: path to image
[image-target-link]: link URL