Markdown¶

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 -->

[cg]: https://docs.openstack.org/charm-guide
[cdg]: https://docs.openstack.org/project-deploy-guide/charm-deployment-guide
[lp-bug-1862392]: https://bugs.launchpad.net/charm-cinder/+bug/1862392

Linking to a header within the current page¶

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

.
.

## Availability zones

.
.
<bottom of page>

<!-- LINKS -->

[anchor-az]: #availability-zones

Admonishments¶

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

Type	Purpose
`Tip`	to provide auxiliary information
`Note`	to inform
`Important`	to accentuate
`Caution`	to draw special attention to
`Warning`	to warn about potential breakage or data loss

Syntax:

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

The text is left-aligned with the asterisks.

Example:

> **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.

Example:

This bit of Python will do the trick:

```python
   import random

   def flip():
       if random.randint(0,1) == 0:
           return "heads"
       else:
           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)

Lists¶

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¶