H2 header

H3 header

H4 header

This document contains formatting standards for creating readable, consistent files using Markdown.

One problem I run into constantly when creating Markdown files is that I waste an ass-load of time fiddling with how the text looks before it gets parsed. Then, after I’m finished writing, I waste even more time adjusting what looks good in my text editor so that it looks good in a browser or Markdown viewer.

Being a masochist, I of course decided to create a guideline I could follow which would produce decent looking output without looking stupid in vim.

Basic conventions for Markdown files

• Wrap all lines at 80 characters.
• Denote bold text using the asterisk format: **bold text**.
• Denote italic text using the underscore format: _emphasized text_.
• Force a linebreak by ending a line with two spaces, no more.

Headings

• Header text must use the atx-style with no closing # character.

• Include a 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 and followed by a newline except at the beginning of a file.

Horizontal Rules

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

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

Lists

• List items must be indented 4 spaces further than their parent.

• Unordered list Items should use - instead of *.

  This is arbitrary text, an unordered list begins on the next line.
      - list item 1
      - list item 2
          - sub-list item
  

• The first level of list items must not be preceded by a newline.

• All lists must be followed by newlines.

  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.
  

• List item lines exceeding 80 characters should, when wrapped, align vertically with the beginning of the preceding line’s text.

    - Large, avian creatures, chocobos roughly act as the equivalent of
      horses, being domesticated for use as mounts...
  

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.
  

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.

  # This wastes our precious 80 character limit.
  | 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:

Other styles

{
  "firstName": "John",
  "lastName": "Smith",
  "age": 25
}

Emphasis

Emphasis, aka italics, with asterisks or underscores.

Strong emphasis, aka bold, with asterisks or underscores.

Combined emphasis with asterisks and underscores.

Strikethrough uses two tildes. Scratch this.

Lists

1. First ordered list item
2. Another item ⋅⋅* Unordered sub-list.
3. Actual numbers don’t matter, just that it’s a number ⋅⋅1. Ordered sub-list
4. And another item.

⋅⋅⋅You can have properly indented paragraphs within list items. Notice the blank line above, and the leading spaces (at least one, but we’ll use three here to also align the raw Markdown).

⋅⋅⋅To have a line break without a paragraph, you will need to use two trailing spaces.⋅⋅ ⋅⋅⋅Note that this line is separate, but within the same paragraph.⋅⋅ ⋅⋅⋅(This is contrary to the typical GFM line break behaviour, where trailing spaces are not required.)

• Unordered list can use asterisks
• Or minuses
• Or pluses

Links

I’m an inline-style link

I’m an inline-style link with title

I’m a reference-style link

I’m a relative reference to a repository file

You can use numbers for reference-style link definitions

Test links blank Google

Or leave it empty and use the link text itself.

URLs and URLs in angle brackets will automatically get turned into links. https://www.example.com or https://www.example.com and sometimes example.com (but not on Github, for example).

Some text to show that the reference links can follow later.

Images

Here’s our logo (hover to see the title text):

Inline-style:

Reference-style:

Highlighting

var s = "JavaScript syntax highlighting";
alert(s);

s = "Python syntax highlighting"
print s

No language indicated, so no syntax highlighting.
But let's throw in a <b>tag</b>.

import urllib2
[...]

Blockquotes

Blockquotes are very handy in email to emulate reply text. This line is part of the same quote.

Quote break.

This is a very long line that will still be quoted properly when it wraps. Oh boy let’s keep writing to make sure this is long enough to actually wrap for everyone. Oh, you can put Markdown into a blockquote.

Styling class

You can add specific plugins to the whitelist key in _config.yml to allow them to run in safe mode.

You can add specific plugins to the whitelist key in _config.yml to allow them to run in safe mode.

You can add specific plugins to the whitelist key in _config.yml to allow them to run in safe mode.

You can add specific plugins to the whitelist key in _config.yml to allow them to run in safe mode.

Orizontal rules

Three or more…

Hyphens

Asterisks

Underscores

YouTube