Skip to main content
Sponsor @cloudposse

Markdown Best Practices

Most of our documentation is provided in Markdown format. Here are some of the conventions and best practices we follow when writing Markdown. Please note that we use the term Markdown loosely to refer to GitHub-flavored Markdown, and we also use quite a bit of MDX, which is what all of our documentation in Docusaurus uses.

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.