---
Title: Markdown Style Guide
Subtitle: A reminder that, first and foremost, markdown is all about readability
Link:
Published: 2015-03-20
Author: Omar Romero
Tag: Posts
Template: blog
---
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.

[image wordwrap.png "wordwrap" center]

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 <code>```</code> 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][1]

[1]: /media/uploads/markdown-style-guide.txt