Awesome
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
- <a name="1"></a> This is enforced locally through redcarpet2's configuration:
:space_after_headers
.