Skip to main content

Markdown Best Practices

Markdown Logo

Code Blocks​

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

Code Block​

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

Table of Options​

Use tables to communicate lists of options.

Here's an example:

Table of Options​
| 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    |
  • :--------: should be used for “Default” and “Required” values
  • :--------- should be used for all other columns
  • Use value for all values

Which will render to something like this:

Example Markdown Table Rendering Example Markdown Table Rendering

Feature List Formatting​

Use this format describe the features & benefits.

Feature List Example​

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

Use Block Quotes​

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

Block Quote Example​

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