/markdown-styleguide

Formatting standards for readable & consistent Markdown

Do What The F*ck You Want To Public LicenseWTFPL

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

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