The Magic of Markdown

Markdown Logo

Markdown is a light-weight markup language that uses a simple, unobtrusive syntax to add formatting, such as headings and italics, to plain text documents. It can be easily converted to many output formats, most notably HTML.

Why is Markdown Magic?

  • It makes writing for the web easy and fun! There are many free applications that create website content from markdown files, like Read the Docs.
  • Unlike HTML, it's easy to read even when you're looking at a raw file.
  • There's a gentle learning curve and lots of online documentation.
  • Many use cases: websites, documents, slides, books, and more!

The Basics

You can create Markdown files using a text editor. The file should have an .md or .markdown extension. You can also use a dedicated Markdown application, like HackMD.

Brief Syntax Primer

To create headings, add hash signs (e.g. # The Magic of Markdown) in front of a word or phrase. Use 1 hash sign # for level 1 headings, use 2 hash signs ## for level two headings, and so on.

The header for this section is written like this in Markdown:
### Brief Syntax Primer

To bold text use two asterisks before and after a word or phrase. 

**bold**
will render as:

bold

For italic use one asterisk before and after a word or phrase.

*italics*
will render as:

italics

Unordered lists are can be created with asterisks *, pluses +, or minuses -.

* October
* November
* December

will render as:
  • October
  • November
  • December

To create a link, enclose the link text in brackets [this guide] and then follow it immediately with the URL in parentheses (https://www.markdownguide.org/). 

Content from [this guide](https://www.markdownguide.org/)
was adapted for this lesson
will render as:

Content from this guide was adapted for this lesson.

Use one back tick around code to create in-line code blocks and three back ticks to create multi-line fenced off blocks.

This line has some `code` in it
will render as:

This line has some code in it.

Hands-on: HackMD

  1. Go to HackMD [https://hackmd.io/]

    With HackMD you can write in Markdown and view the formatted output simultaneously

  2. Click "Try it out"
  3. Title your document by adding a level 1 heading.
  4. Start a ordered list of the things your future self should know.

    Use this handy cheatsheet to look-up common Markdown elements

  5. Add a gif to your document.

Discussion

Now that you've had some time to experiment with Markdown what were you able to do, or what did you struggle with?