Markdown Formatting “Best Practices”

adminBest Practices0 Comments

Markdown Formatting Best Practices

Using Markdown is essential for clear communication on mediums such as GitHub, Slack or just plan text. Here are some of our recommendations on when to use certain conventions.

Code Blocks

Use code blocks for anything more than 1 line. Use `code` for inline code, filenames, commands, etc.

```
# This is a code block
```

Tables

Use tables to communicate lists of options. 

:--------: should be used for “Default” and “Required” values

:--------- should be used for all other columns

Use  ``  for empty defaults

Use `value`for all values

Here's an example:

|  Name       |  Default |  Description                                  | Required |
|:------------|:--------:|:----------------------------------------------|:--------:|
| namespace   | ``       | Namespace (e.g. `cp` or `cloudposse`)         | Yes      |
| stage       | ``       | Stage (e.g. `prod`, `dev`, `staging`)         | Yes      |
| name        | ``       | Name  (e.g. `bastion` or `db`)                | Yes      |
| attributes  | []       | Additional attributes (e.g. `policy`)         | No       |
| tags        | {}       | Additional tags  (e.g. `map("Foo","XYZ")`)    | No       |

Which will render to something like this:

Features 

Use this format describe the features & benefits.

```
1. **Feature 1** - Explanation of benefits
2. **Feature 2** - Explanation of benefits
```

Quotes

Reference copyrighted text, quotes, and other unoriginal copy using `> `

```
> Amazon Simple Storage Service (Amazon S3) makes it simple and practical to collect, store, and analyze data - regardless of format – all at massive scale.
```

Leave a Reply

Your email address will not be published. Required fields are marked *