markdown.md

Start Using Markdown (Stop Using Word)

Problems with Word

• The file is serialized in a binary format that can only be viewed and decoded with the Word application.
• The Word application is proprietary, closed-source, and costs money.
• The file is not suited for diffing via source control.
• Sharing and collaborating is difficult, and typically involves emailing a file back and forth.

Benefits of Word

• Track changes, but version-itis can clobber and confound this benefit.
• Grammar check
• Spell check

Benefits of Markdown

• The file is serialzed in a text format that can be viewed by any text editor.
• There is no mandatory application that must be used to view Markdown.
• Markdown is not proprietary, and costs nothing.
• The file is extremely well suited for diffing via source control.
• Sharing and collaborating is easy, and favors source control, avoiding emailing files back and forth.
• Track changes is implicit when used on a repository.

Limitations of Markdown

• Grammar check nonexistent
• Spell check nonexistent

Cheat Sheet

To get started, reivew the Markdown Guide.

Below the Markdown Cheat Sheet is restated as a version local to this repository.

This Markdown cheat sheet provides a quick overview of all the Markdown syntax elements. It can’t cover every edge case, so if you need more information about any of these elements, refer to the reference guides for basic syntax and extended syntax.

Basic Syntax

These are the elements outlined in John Gruber’s original design document. All Markdown applications support these elements.

Element	Markdown Syntax	Rendered Output
Heading	# Heading 1 ## Heading 2 ### Heading 3	Heading 1 Heading 2 Heading 3
Bold	**bold text**	bold text
Italic	*italicized text*	italicized text
Blockquote	> blockquote	> blockquote
Ordered List	1. First item 2. Second item 3. Third item	First item Second item Third item
Unordered List	- First item - Second item - Third item	First item Second item Third item
Code	code
Horizontal Rule	---
Link	[title](https://www.github.com)	GitHub
Image	

Extended Syntax

These elements extend the basic syntax by adding additional features. Not all Markdown applications support these elements.

Element	Markdown Syntax
Table	| Syntax | Description | | ----------- | ----------- | | Header | Title | | Paragraph | Text |
Fenced Code Block	``` {   "firstName": "John",   "lastName": "Smith",   "age": 25 } ```
Footnote	Here's a sentence with a footnote. [^1] [^1]: This is the footnote.
Heading ID	### My Great Heading {#custom-id}
Definition List	term : definition
Strikethrough	~~The world is flat.~~
Task List	- [x] Write the press release - [ ] Update the website - [ ] Contact the media
Emoji (see also Copying and Pasting Emoji)	That is so funny! :joy:
Highlight	I need to highlight these ==very important words==.
Subscript	H~2~O
Superscript	X^2^

Basic Style

Below the basic style Markdown Guide is restated as a verion local to this repository.

Heading Best Practices

• Markdown applications don't agree on how to handle a missing space between the number signs (#) and the heading name. For compatibility, always put a space between the number signs and the heading name.

✅ Do this	❌ Don't do this
# Here's a Heading	#Here's a Heading

• Put blank lines before and after a heading for compatibility.

✅ Do this	❌ Don't do this
Try to put a blank line before... # Heading ...and after a heading.	Without blank lines, this might not look correct. # Heading Don't do this!

Paragraphs Best Practices

To create paragraphs, use a blank line to separate one or more lines of text.

Markdown	HTML	Rendered Output
I really like using Markdown. I think I'll use it to format all of my documents from now on.	<p>I really like using Markdown.</p> <p>I think I'll use it to format all of my documents from now on.</p>	I really like using Markdown. I think I'll use it to format all of my documents from now on.