Styleguide

Jul 9, 2015 • Martin

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

Headings

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

Code

Tables

Like fenced code blocks, tables in Markdown are provided by Markdown Extra which seems to be pretty widely implemented.

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.