Markdown Style Guide

Markdown is a text formatting style that was conceptualized with easy-to-write and easy-to-read principles in mind. All the entries in this blog are written in Markdown and the rationale for it is that I could be able to write and read the posts anywhere with a simple text editor and that they would be easy to read.

What I realized, is that the files that I was producing were not easy to read at all. They seemed like an agglomeration of text and tags that had no structure. As John Gruber himself said:

Readability, however, is emphasized above all else. A Markdown-formatted document should be publishable as-is, as plain text, without looking like it’s been marked up with tags or formatting instructions.

That was not what I was producing with my Markdown files at all.

In order to achieve the ethos of the format, here are some guidelines that I’ll use from now on to write the entries for this blog.

Overview

• 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.
• Use Setext (underline) style for headers.
• Indent and wrap blockquotes and lists.
• Use an hyphen for horizontal rules; should be 80 characters long.
• Inline code is delimited by single backtick characters.
• Code blocks are indented four spaces deep.

Wrap the text

Use a new line at 80 columns. Not doing this will cause the text to be a long line unless word wrap is used in the text editor, and even then, the text lines will be as long as the size of the text editor’s window. By using a new line every 80 cols will make the text seem more like a book’s page, pleasant to look at and easier to read.

Simplify the syntax

Denote bold text using the asterisk format: **bold text** and italic text using the underscore format: _italic text_. The Markdown specification allows for using the same character for both formats but when reading, it is easier to differentiate between both if different formats are used.

When forcing a new line, it is better to use two spaces only. No need to use a chain of eight spaces after the period.

Headers

If there is no need to go beyond two levels of headers, opt for using the setext style for headers. It makes it nearly impossible to miss a header when quickly glancing at a document.

Header 2
--------

Instead of:

## Header 2

Blockquotes

Indent blockquotes two spaces further than their parent. Also, it is a better practice to break and wrap a long quote.

This looks better

> U.S. stocks rose on Friday, putting the S&P 500 on
> track to snap a three-week streak of losses, following
> upbeat results from Nike, further gains in biotechs
> and a pullback in the dollar

Than this

> U.S. stocks rose on Friday, putting the S&P 500 on track to snap a three-
week streak of losses, following upbeat results from Nike, further gains in 
biotechs and a pullback in the dollar

Lists

Again, indent lists two spaces further than their parent. Break and indent long list item lines to match the line above. Use numbers for ordered lists and - for unordered lists.

- Lorem ipsum dolor sit amet, consectetuer adipiscing elit. Aliquam 
hendrerit mi posuere lectus. Vestibulum enim wisi, viverra nec, fringilla 
in, laoreet vitae, risus.
- Donec sit amet nisl. Aliquam semper ipsum sit amet velit. Suspendisse id 
sem consectetuer libero luctus adipiscing.

vs.

- Lorem ipsum dolor sit amet, consectetuer adipiscing elit.
  Aliquam hendrerit mi posuere lectus. Vestibulum enim wisi,
  viverra nec, fringilla in, laoreet vitae, risus.
- Donec sit amet nisl. Aliquam semper ipsum sit amet velit.
  Suspendisse id sem consectetuer libero luctus adipiscing.

Horizontal Rules

Use - for horizontal rules (instead of asterisks or underscores). Following another basic convention of this guide, horizontal rules should span 80 characters for readability.

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

Sample Code

Inline code must use single backticks and must not have spaces between the backtick characters and the code.

For code blocks, it is best if the code is indented with four spaces from the parent element and must be preceded and followed by a newline. Please, do not use the ``` sequence, it just looks fugly.

I will update this guide as I come across new items that may need to be added. The source .txt file for this entry can be seen here