├── LICENSE └── README.md /LICENSE: -------------------------------------------------------------------------------- 1 | DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE 2 | Version 2, December 2004 3 | 4 | Copyright (C) 2004 Sam Hocevar 5 | 6 | Everyone is permitted to copy and distribute verbatim or modified 7 | copies of this license document, and changing it is allowed as long 8 | as the name is changed. 9 | 10 | DO WHAT THE FUCK YOU WANT TO PUBLIC LICENSE 11 | TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION 12 | 13 | 0. You just DO WHAT THE FUCK YOU WANT TO. 14 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | # Style Guidelines: Markdown 2 | 3 | This document contains formatting standards for creating readable, consistent 4 | files using Markdown. 5 | 6 | One problem I run into constantly when creating Markdown files is that I waste 7 | an ass-load of time fiddling with how the text looks before it gets parsed. 8 | Then, after I'm finished writing, I waste even more time adjusting what looks 9 | good in my text editor so that it looks good in a browser or Markdown viewer. 10 | 11 | Being a masochist, I of course decided to create a guideline I could follow 12 | which would produce decent looking output without looking stupid in vim. 13 | 14 | ## Basic conventions for Markdown files 15 | 16 | - Wrap all lines at 80 characters. 17 | - Denote **bold** text using the asterisk format: `**bold text**`. 18 | - Denote _italic_ text using the underscore format: `_emphasized text_`. 19 | - Force a linebreak by ending a line with two spaces, no more. 20 | 21 | ## Headings 22 | 23 | - Header text must use the `atx-style` with no closing `#` character. 24 | - Include a space between the `#` and the text of the Header^[1](#1). 25 | 26 | ``` 27 | # Header 1 28 | ## Header 2 29 | ### Header 3 30 | ``` 31 | 32 | - Headers spanning more than 80 characters should be re-evaluated. 33 | - Headers must be preceded and followed by a newline except at the beginning 34 | of a file. 35 | 36 | ## Horizontal Rules 37 | 38 | The convention for horizontal rules in this style guide is to use hyphens 39 | (instead of asterisks or underscores). Following another basic convention of the 40 | guide, horizontal rules should span 80 characters for readability. 41 | 42 | ``` 43 | -------------------------------------------------------------------------------- 44 | ``` 45 | 46 | ## Lists 47 | 48 | - **List items** must be indented 4 spaces further than their parent. 49 | - Unordered list Items should use `-` instead of `*`. 50 | 51 | ``` 52 | This is arbitrary text, an unordered list begins on the next line. 53 | - list item 1 54 | - list item 2 55 | - sub-list item 56 | ``` 57 | 58 | - The first level of list items must not be preceded by a newline. 59 | - All lists must be followed by newlines. 60 | 61 | ``` 62 | This text precedes a list of things. 63 | - list item 1 64 | - list item 2 65 | 1. sub-list item 1 66 | 2. sub-list item 2 67 | 68 | - list item 3 69 | - list item 4 70 | 71 | This is text of any kind that follows a list. 72 | ``` 73 | 74 | - List item lines exceeding 80 characters should, when wrapped, align 75 | vertically with the beginning of the preceding line's text. 76 | 77 | ``` 78 | - Large, avian creatures, chocobos roughly act as the equivalent of 79 | horses, being domesticated for use as mounts... 80 | ``` 81 | 82 | ## Code 83 | 84 | - **Inline code** must use single backticks and must not have spaces between 85 | the backtick characters and the code. 86 | 87 | ``` 88 | # Bad 89 | ` .this-is-wrong ` 90 | 91 | # Good 92 | `.this-is-good` 93 | ``` 94 | 95 | - **Fenced code blocks** must be preceded and followed by a newline. 96 | - When used inside _list items_, **fenced code blocks** must be indented as 97 | if they were one level deeper that the list item that contains them. 98 | 99 | ``` 100 | - This list item contains a fenced code block. 101 | - Let's show how it might interact with a list. 102 | 103 | ``` 104 | .code-example { 105 | property: value; 106 | } 107 | ``` 108 | 109 | There is a newline above this paragraph because it is both the end of a 110 | list and because it follows a fenced code block. 111 | ``` 112 | 113 | ## Tables 114 | 115 | Like fenced code blocks, tables in Markdown are provided by Markdown Extra 116 | which seems to be pretty widely implemented. 117 | 118 | - Pipe characters must be preceded and followed by spaces for readability. 119 | - Table column width should be determined by the longest cell in the column. 120 | - Always format tables so they are readable in pre-processing. 121 | 122 | ``` 123 | # This is completely unreadable, although it is technically valid. 124 | table header | other table header 125 | --- | --- 126 | table data | other table data 127 | ``` 128 | 129 | - Never use preceding or trailing pipes when writing tables. 130 | 131 | ``` 132 | # This wastes our precious 80 character limit. 133 | | table header | other table header | 134 | | ------------ | ------------------ | 135 | | table data | table data | 136 | ``` 137 | 138 | - Tables must always be preceded and followed by newlines. 139 | 140 | ### Table example: 141 | 142 | _This table meets all the criteria:_ 143 | 144 | ``` 145 | Group | Domain | First Appearance 146 | ------------------------- | --------------- | ---------------- 147 | ShinRa | Mako Reactors | FFVII 148 | Moogles | MogNet | FFIII 149 | Vana'diel Chocobo Society | Chocobo Raising | FFXI:TOAU 150 | ``` 151 | 152 | _A handsome table in pre-processed markdown is also handsome when rendered:_ 153 | 154 | Group | Domain | First Appearance 155 | ------------------------- | --------------- | ---------------- 156 | ShinRa | Mako Reactors | FFVII 157 | Moogles | MogNet | FFIII 158 | Vana'diel Chocobo Society | Chocobo Raising | FFXI:TOAU 159 | 160 | 161 | ## Footnotes 162 | 163 | 1. This is enforced locally through redcarpet2's configuration: 164 | `:space_after_headers`. 165 | 166 | 167 | --------------------------------------------------------------------------------