Introduction to Markdown

a better way to write for the web

Quick Course Navigation

[toc]


You will Learn:

  • What is Markdown?
  • Why is it useful?
  • How can I get started?
  • Where can I use it?

What is Markdown?

A simple text-based syntax, designed to be human-readable, easy to write, which converts effortlessly to valid HTML code.


Let’s break down what that means:

Text-based

Even though it does a lot of the things we use word processors (like MS Word) for, Markdown is not a proprietary program — it’s not a program at all! It’s more like a set of simple rules for formatting your text so it looks great on the web.


You can write Markdown in any text editor, and read it on any device. It doesn’t matter if it’s Mac, Windows, Linux, Android, iOS, Windows Phone, or a 1989 Amiga — since it’s text-based, it works everywhere. For this reason, companies, governments, and academic groups are starting to adopt Markdown as a future-proof format for important documents that need to stand the test of time.


Human-readable

Have you ever tried to look at HTML code and gotten overwhelmed by all the tags and formatting? Markdown looks a lot like plain text, with a few special characters thrown in. These characters tell the computer how to convert your writing to HTML, but they also look good in plain-text and don’t interfere with the reading experience.


Converts to Valid HTML Code

The simple tags we add to Markdown tell a converter program how to turn your writing into valid HTML code. This means that the resulting HTML code will conform to international standards for accessibility and interoperability. From the writer’s perspective, though, it just means it’s easy to share your work from Markdown into any format your collaborators might need with no fuss.


That’s why my documents start in Markdown, so I can easily output them as websites, blog posts, presentations, PDFs, email messages, and more.


Why is it Useful?


A great way to take notes/ outlines

I love taking notes in Markdown because headings allow me to add an outline to my thoughts, organizing ideas into hierarchical order. The markdown editor formats these different headings into different sizes so I can see visually how ideas are related and organized.


A starting place for blog posts and other web writing

Most of us write in WYSIWYG editors, whether that’s in a word processor like MS Word or a blog editing window. These tools give us lots of options for adding italics, bold, hyperlinks and more, but they tempt us to fidget with how our writing looks instead of focusing on what it says.


Markdown is designed to let you keep your hands on the keyboard and your mind on your words so you don’t get distracted by visual concerns. This really helps your productivity so you can get your ideas out faster.


Export to HTML, PDF, email, presentations, etc.

If your first draft is in Markdown, it becomes easy to export your writing to almost any other format. Most markdown editors have a one-click solution to export to HTML and PDF, but you can also copy-paste from the HTML preview into other visual tools like PowerPoint, Keynote, Sketch, an email message, or any other visual editor.


I even made this presentation in Markdown, then copied my Markdown syntax into Hacker Slides, which formatted them in a web-based presentation! So simple!


A great way to track “to do” items

You can use the following syntax to create a to-do item.

-[ ] pick up chips and salsa

And do this to mark that item as done:

-[x] pick up chips and salsa

HarooPad will even format this syntax as a checkbox so you can easily see what you have left to do.

picture of a markdown todo list


Sync this Markdown todo.md doc between all your different devices (using something like Dropbox) and you have a simple system for tracking your tasks!


How can I get started?


Get a nice markdown editor

Though you don’t need a dedicated Markdown editor (any text editor will work), they add a lot of nice creature comforts to your writing experience. My favorite ones happen to be free, too, so it’s a no-brainer to add one of these powerful apps to your writing toolkit:


HarooPad (Mac, Windows, Linux)

One of my favorites, and it’s free on all major desktop platforms. Open source and full featured, it’s a great option on any platform.

MacDown (Mac)

Another great, free, open source option, MacDown is a new upstart in the Markdown game but I find it full featured and comfortable for my needs.


Of course, you can write Markdown in any text editor you like. A plain text editor like TextEdit will let you write Markdown, but doesn’t have any of the extra nice tools like HTML previews, syntax completion, and highlighting.


Most developer code editors like SublimeText, Panic Coda, and Atom Editor recognize Markdown code and can assist you with HTML previews, syntax completion, and highlighting.

Other popular writer-oriented tools like Scrivener, Ulysses, and Byword also offer Markdown tools, so you have many options to meet your specific needs and budget.


If you prefer web-based tools over desktop ones, check out Dillinger.io, the best web-based markdown editor I know of. Free.

Learn the basic syntax

– Headings

Headings are an important feature of HTML that often get overlooked by writers who are used to visual tools. This is a shame, because they are critical in making your writing accessible to users with disabilities.

Beyond making your writing accessibly by all, headings help organize your work, provide clarity and structure to your writing, and are a critical component of making your work rank highly in search engine results.


The syntax is simple — Just add a pound sign/ hash mark (#) before some text to make that a Heading 1 <h1>.

Example:
# Heading I

Two hashes ## makes it a Heading 2 <h2>, 3 ### makes it an <h3> and so on.

Example:

## Heading 2

### Heading 3

Try it yourself!
  • Create a main title for your document, and assign it as a Heading 1.
  • Add three sub-topics to your document, and assign each a Heading 2.
  • Under one of your subtopics (h2), add a sub-subtopic as a Heading 3.

Note:
Headings usually go from h1 (the page title or main idea) to h6, but you don’t use them sequentially. Rather, you use them like levels in an outline, organizing your document into clear sections, organized by topics.

Below, we go from the Main Idea (h1) through some subheadings (both are h2s), and then we see some sub-subheadings (h3s) to further clarify the information.

A document with properly nested headings

– Links

Hyperlinks can be added two different ways. Let’s start with the inline link, which follows this syntax:

  • The text that will become hyperlinked goes inside of brackets [].
  • The URL the link points to goes inside of parentheses ().

[The text inside your link](the URL your link points to)


for example:

The markdown syntax
I really love [TrueSchool's Markdown Class](https://trueschool.me/markdownclass)!

produces this HTML:

I really love TrueSchool’s Markdown Class!


Try it yourself!
  • Write a sentence and make only a few words into a link to trueschool.me.

(Note: If you’re using a Markdown editor, it will highlight a different color to let you know you’re doing it right. This is helpful and encouraging when you’re still learning the syntax. )


– images

The syntax for an image is

![the title of your image](the URL where your image can be found)
for example

![The beautiful world of Markdown](http://is.gd/n5wlcJ)

Produces
The beautiful world of Markdown

Try it yourself!

– Type out the syntax of an image, using this URL where it belongs: http://placekitten.com/450/450

– plain text

Plain text is simple — just write plain text.

Press return twice to make it a paragraph.

Simple!

– bold & italics

In most markdown editors, you can type Cmd+B to bold (Ctrl on Windows), or Cmd+I to italicize.

The regular text notation is to surround text with one asterisk * for italics, and two for bold.

*italics*italics

**bold**bold


Get deeper into it

Practice, practice practice!

Use your markdown editor for your next big writing project, whether that’s taking notes in class, writing a blog post or term paper, or whatever you like writing best.

Practice formatting with headings, links, and bold/italics as you write.

Use this Cheat Sheet

Markdown Cheat Sheet


Pro Tip:

If you’re on Mac, check out Brett Terpstra’s Markdown Service Tools and SearchLink. They put a ton of tricky markdown functions in your Mac’s Services menu so you can quickly format and reformat text from HTML to Markdown and back again.

 


 

Searchlink Demo -- automatic markdown linking

SearchLink is amazing. JUST AMAZING. You highlight some text and hit the keystroke for SearchLink. It runs a quick Google search in the background for that text and automatically turns it into a link to the top ranked Google search result.

SO EASY


Thanks for coming and learning about Markdown.

What do you think?

Stay in touch and let me know how it’s going:

@tedcurran