Markdown Standards
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 Header1.
# 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`
Code Blocks can be writen with 3 backticks enclosing the code like the following
```
# include<stdio.h>
int main(){
printf("Hello World");
return 0;
}
```
Syntax Highlighting for specific languages can be easily done by writing the name of the language right after the opening backticks
Highlighting C programming syntax
```c
# include<stdio.h>
int main(){
printf("Hello World");
return 0;
}
```
renders
# include<stdio.h>
int main(){
printf("Hello World");
return 0;
}
Highlighting Java Programming Syntax
```java
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
```
renders
class HelloWorld {
public static void main(String[] args) {
System.out.println("Hello, World!");
}
}
Similarly you can use for python, c++, php etc.,
- 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.
```css
.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.
