Markdown

“Easy reading is damn hard writing.” — Nathaniel Hawthorne

Table of contents

  1. Blockquote style
  2. Emphasis style
  3. Fenced code style
  4. Header style
  5. Lists
    1. Unordered list style
    2. Ordered list style
  6. Table
    1. Optional table pipe
    2. Wrap table cell
  7. Formatting
    1. Max line length
    2. Vertical spacing

Blockquote style

Pandoc: Block quotations

Use lazy form, where only the first line is prefixed with a blockquote character, subsequent lines are prefixed with indentation.

BeforeAfter
> Lorem ipsum dolor sit amet,
> consectetur adipiscing elit.
> Lorem ipsum dolor sit amet,
  consectetur adipiscing elit.

Emphasis style

GitHub: Styling text

Stylize text with asterisks while underscores act as subsequent highlights.

BeforeAfter
***Lorem ipsum** dolor sit amet,*
consectetur adipiscing elit.
_**Lorem ipsum** dolor sit amet,_
consectetur adipiscing elit.

Fenced code style

GitHub: Quoting code

Use backticks to create fenced code blocks, not the optional 4 spaces indentation.

BeforeAfter
    git status
    git add
    git commit
```
git status
git add
git commit
```

Header style

GitHub: Headings

ATX headings are preferred over Setext headings. Setext headings are long and do not support over 2 levels of headings.

BeforeAfter
Lorem ipsum
===========
# Lorem Ipsum

Lists

Unordered list style

GitHub: Lists

Use hyphens to create unordered lists and nested lists. Asterisk is already associated with highlights, and plus is not as common.

BeforeAfter
* Foo
+ Bar
- Foo
- Bar

Ordered list style

Google: Use lazy numbering for long lists

Use fixed numbers for ordered lists to avoid confusion with nested lists. There should be four spaces after the period to better align with nested list items.

BeforeAfter
1) Foo
2) Bar
   - Baz
1.  Foo
1.  Bar
    - Baz

Table

Optional table pipe

Google: Tables

Never use the optional pipe at each side of the table.

BeforeAfter
| Column 1 | Column 2 | Column 3 |
| --- | --- | --- |
| Foo | Bar | Baz |
Column 1 | Column 2 | Column 3
--- | --- | ---
Foo | Bar | Baz

Wrap table cell

GitHub: Creating a table

Always wrap the cell content and pad with a space on each end. Column alignment line should be 3 dashes and optional colon.

BeforeAfter
Column 1 | Column 2
:------- | -------:
Foo      | Bar
Column 1 | Column 2
:--- | ---:
Foo | Bar

Formatting

Max line length

GitHub: Links

Keep characters in a line to a maximum of 80 characters.

Separate a link to a new line only if the text (not the link) exceeds 80 characters. In the example below, a paragraph is not split because [hyperlink] can still fit in the first column even though the link is more than 80 characters.

BeforeAfter
Lorem ipsum dolor sit amet, consectetur adipiscing elit.
[hyperlink](path/to/hyperlink/).
Lorem ipsum dolor sit amet, consectetur adipiscing elit. [hyperlink](path/to/hyperlink/).

Vertical spacing

GitHub: Spacing

Separate headings, paragraph, and everything in between with 1 blank line. Extra lines are ignored when rendered.

BeforeAfter
# Heading
Lorem ipsum dolor sit amet.
# Heading

Lorem ipsum dolor sit amet.