You can learn the basics of Markdown in 5 minutes, so I’ll teach you those basics now with a simple Markdown guide. Learn a tiny bit of code to make your life easier. Trust me, this is easy.
- What is Markdown, and why would you use it?
- Markdown coding basics
- Additional Markdown options
- Markdown editors
What is Markdown, and why would you use it?
What is Markdown?
Markdown is a simple coding language built for writers. It allows you to format your text by preceding or surrounding it with special characters.
You most likely write in a rich text editor that has formatting buttons for adjusting font sizes, font styles, heading levels, text colors, alignment, and so on.
When it comes time to adjust your formatting, you take your hand off the keyboard and use your mouse to select the formatting option you want.
With Markdown, your hands never have to leave your keyboard. Just type _an italicized word_ wrapped in underscores (asterisks also work), and your Markdown editor will italicize the text.
Don’t worry: when you export your text, it will eliminate the code (in this case, the underscores) and show the italicized text.
Similar code (and just as simple) is available for headings, bold text, lists, quotes, etc.
Imagine you’re editing and want to see the precise format settings of a heading.
In a rich-text editor, you’ll select the text and look at the row of settings above the editor.
In Markdown, you can see how many pound signs precede the line with a glance.
This makes editing much easier.
Have you ever copied and pasted from one program to another and discovered your text was formatted inconsistently or included weird characters?
Markdown is plain text, so copying from one application to another will never cause surprises.
Markdown coding basics
This is the most simple. Just type. If you’re exporting to HTML, <p> tags will be added automatically.
Here's a paragraph. And here's the next paragraph. This is easy as f*%$!
To make a heading level 1-6, type 1-6 #s (pound sign, number sign, hashtag), a space, then the heading text.
# This is a heading 1 ## This is a heading 2 ### This is a heading 3
Appearance in Bear, a popular Markdown editor
Note: the pound signs are there, but this particular app hides them. They can still be edited as simple text.
Bold and italic text
To get bold text, wrap it in a single * or _ (asterisk or underscore).
Wrap the text in a double * or _ for italic.
The asterisk and underscore are interchangeable, but I like to use an underscore for italic and two asterisks for bold.
Here is some _italicized text_. Here is some **bold text**.
Appearance in Bear app
A single asterisk (a hyphen also works), a space, then the text will create an unordered list.
* List item 1 * List item 2 * List item 3
For an ordered list, just replace the asterisk with a number.
1. List item 1 2. List item 2 3. List item 3
If you need to nest a list inside another list, just indent the line(s).
* List item 1 * List item 2 * Sublist item 1 * Sublist item 2 * List item 3
Appearance in Bear app
Type a right-pointing angle bracket (a greater than symbol), a space, and the quote.
If exported to HTML, the quote will be wrapped in
> It is no measure of health to be well adjusted to a profoundly sick society. --Jiddu Krishnamurti
Appearance in Bear app
Note: the angle brackets are there, but this particular app hides them. They can still be edited as simple text.
Type an exclamation point, then wrap the alt text you would like to use in square brackets, then wrap the URL of the image in parentheses.
Wrap the anchor text of your link in square brackets, then wrap the destination URL for your link in parentheses.
Sometimes you need a line across the page to break up your content. In HTML, this becomes an
Just type 3 or more hyphens in a row on their own line. (You can also use asterisks or underscores if you prefer.)
Additional Markdown options
For most book and article writers, this is all you’ll ever need. You’re done! But if you’d like to get more advanced, let’s continue…
Inline code snippets
If you write about coding, you might need a code block to display that code without executing it and to style it properly.
Just wrap your code in single backquotes.
Code example for inline code block
A small bit of `<b>inline code</b>`.
Appearance in Bear app
Fenced code blocks
For larger, multiline sections of code, type 3 backquotes on one line, go to the next line and start your code, and after the final line of code, make another line of 3 backquotes.
Syntax highlighting is available in some editors. You can define the coding language next to the first three backquotes.
```html <div class="example-text"> <p>Code goes here...</p> <p>and continues here.</p> </div> ```
Escaping Markdown code.
Maybe your Markdown editor is italicizing text when you use an asterisk, and in this case, you want to display the asterisk for your readers.
You can force the code to display rather than executing by escaping the special characters.
To escape any character, just put a backslash before it. When exported, Markdown will remove the backslash and display the character.
I meant to say \*duck off\*.
Combining HTML with Markdown
What if you want to include some custom HTML within your document?
For example, maybe you want some floating divs. Markdown does not support div tags.
Just type your HTML wherever you would like it to appear! Markdown will detect HTML code automatically and leave it alone.
Once finished with your HTML part, you can go write back to typing Markdown.
Note that all HTML tags must be closed before resuming Markdown.
## Heading <div class="alignright">Here's div that's floated right.</div> **And back to Markdown!**
What about alignment, text colors, and so on?
You’ll rarely (probably never) need to center your text or change font colors.
There are exceptions. For example, maybe you want to use a different font for your headings.
Whether exporting to HTML or another filetype, stylesheets define the style of particular elements. There’s no need to worry about these things while writing.
In other words, rather than defining the font every time a heading is needed, a stylesheet will apply the font to every heading automatically.
Most major text editors, these days, support Markdown in some form. WordPress, for example, allows you to type or paste Markdown code into the editor, and it will format the text appropriately.
But when writing, you may want to use a dedicated editor that focuses on non-destructive plain text Markdown code.
Some Markdown editors I love:
*I use Mac, so these options may not be available on Windows or Chrome OS. Your OS will have similar options available.
I mostly use Bear for note-taking and Ulysses for fiction and article writing.
With these apps, you also benefit from automatic cloud syncing. Cloud syncing is peace of mind. Someone could steal every computer and hard drive I own and I’d know my writing is safe.
Full Markdown syntax documentation
Dig deeper into the options by reading the full Markdown syntax documentation at Daring Fireball.