Markdown Style Guide

This document contains formatting standards for creating readable, consistent files using Markdown - without wasting time changing formatting.

Basic conventions for Markdown files

Denote bold text using the asterisk format: **bold text**.
Denote italic text using the underscore format: _emphasized text_.
Never leave trailing whitespace. Force linebreaks by using a blank line between paragraphs, not trailing spaces (it's much easier to read in an editor anyway).
End files with a newline (see this explanation).
Never use consecutive blank lines outside of code samples. A single blank line is always enough in Markdown.

Headings

Header text must use the atx-style with no closing # character.
Include a single space between the # and the text of the Header^1.
```
# Header 1

## Header 2

### Header 3
```
Headers spanning more than 80 characters should be re-evaluated.
Headers must be preceded by a newline (except at the beginning of a document) and followed by a newline always.
The first header in a file should be an h1.
Headers should never increase by more than one "level" from one header to the next. Think of higher-level headers as though they are nested within their parent, forming a hierarchy like the Table of Contents.
```
This is wrong.

# Header 1

### Header 3
```
```
This is correct.

# Header 1

## Header 2
```

Horizontal Rules

The convention for horizontal rules in this style guide is to use hyphens (instead of asterisks or underscores). Horizontal rules should span 80 characters for readability.

--------------------------------------------------------------------------------

Lists

Unordered lists are denoted with a - (a hyphen and a space). Hyphens tend to be consistent across monospace fonts (being displayed at half of the line height) and seem to be the most common "list character" anyway.

Nested list items must be indented 2 spaces further than their parent.

This is arbitrary text, an unordered list begins on the next line.

- list item 1
- list item 2

  - sub-list item

Lists must be preceded by a newline (except at the beginning of a document) and followed by a newline always.

This text precedes a list of things.

- list item 1
- list item 2

  1. sub-list item 1
  2. sub-list item 2

- list item 3
- list item 4

This is text of any kind that follows a list.

Code

Inline code must use single backticks and must not have spaces between the backtick characters and the code.
```
# Bad
` .this-is-wrong `

# Good
`.this-is-good`
```
Fenced code blocks must be preceded and followed by a newline.

When used inside list items, fenced code blocks must be indented as if they were one level deeper that the list item that contains them.

- This list item contains a fenced code block.
- Let's show how it might interact with a list.

  ```
  .code-example {
    property: value;
  }
  ```

There is a newline above this paragraph because it is both the end of a list and because it follows a fenced code block.

As long as the parser supports it; code blocks should not be denoted with indentation. Using back-ticks is much more explicit than 4 spaces or 1 tab.

Tables

Like fenced code blocks, tables in Markdown are provided by Markdown Extra which seems to be pretty widely implemented.

Pipe characters must be preceded and followed by spaces for readability.
Table column width should be determined by the longest cell in the column.

Always format tables so they are readable in pre-processing.

# This is completely unreadable, although it is technically valid.

table header | other table header
--- | ---
table data | other table data

Never use preceding or trailing pipes when writing tables.

| table header | other table header |
| ------------ | ------------------ |
| table data   | table data         |

Tables must always be preceded and followed by newlines.

Table example

This table meets all the criteria:

Group                     | Domain          | First Appearance
------------------------- | --------------- | ----------------
ShinRa                    | Mako Reactors   | FFVII
Moogles                   | MogNet          | FFIII
Vana'diel Chocobo Society | Chocobo Raising | FFXI:TOAU

A handsome table in pre-processed Markdown is also handsome when rendered:

Group	Domain	First Appearance
ShinRa	Mako Reactors	FFVII
Moogles	MogNet	FFIII
Vana'diel Chocobo Society	Chocobo Raising	FFXI:TOAU

Footnotes

This is enforced locally through redcarpet2's configuration: :space_after_headers.

notslang / markdown-styleguide