Markdown Not Markup - Easy Everyday Workflow for the Web

Open Source Workshop, April 7, 2014

1. What is Markdown

Quick n dirty description:

Markdown is web shorthand.

It was created by John Gruber of Daring Fireball and his goal was basically to make it as readable as possible. He's adhered to that design philosophy quite thoroughly; it is ideal for document creation on and off the web.

2. Where & why would you use it?

For pretty much the same reasons you would use HTML.

If you want to have even the most basic of web presences, you're going to need to know HTML. Yes, you can use premades, but those are limited in their function and scope. HTML is the standard for creating web pages, and everybody should learn to at least read it.

Except wait! There's more!

If you don't want to wade into HTML just yet, Markdown is an easy and much more layperson-friendly alternative. You can use the two interchangeably in a markdown document. Markdown offers some distinct advantages over HTML though:

From One to Many

Simple format can output many formats (html, doc, pdf, slideshow)

Markdown is plaintext in its simplest form, which means that it can be written anywhere. There are many dedicated MD editors (see list below), but MD is so simple that you don’t really need special tools to debug it. In fact, you really shouldn’t have to debug it at all because it’s meant to be read more or less as is. Admittedly HTML is pretty forgiving as far as languages go, but markdown is even more lenient.

3. Web Walkthrough & Demo

Language basics:

Any of the above editors can cheerfully handle the core library of md without a problem. Run through the basic syntax:

Create & save a file:

Firefox can handle .md straight out of the box, and conveniently it's included in the toolkit as well. For web work it's usually best to convert to HTML though and then stick that onto your server/wherever your website is. Fortunately, most editors will save flexibly between the two, and there are a plethora of conversion tools available.

After saving: compare the HTML and MD files to see how one merges into the other fairly seamlessly.

CSS magic: shortcode for adding an external css stylesheet

<link rel="stylesheet" type="text/css" href="http://digital-english.net/summer2012/markdown-grayish.css" > </link>

Alternative CSS files for Markdown docs

The relationship between CSS and Markdown:

You can use pure MD without any HTML tags just fine. If you want to use/design your own HTML classes/ids, though, HTML tags are a must. For basic customization, though, md works just fine.

Instant import to web:

Surprisingly enough, IUP provides a PeopleSpace that students can use. Place a file inside your wwwiup folder on your H: drive (name it index.html, preferably) and it'll pop right up at people.iup.edu/yourfourlettershere.

4. Markdown tools:

Firefox Markdown Editor

Plugin has basic features and can get a tad clunky to work with at times, but it'll do a servicable job. You can save as MD or export to HTML. Doesn’t appear to be able to handle markdown tables or anything out of the core markdown spec.

Dillinger.io

Has some CSS of its own prebuilt, which is nice, but doesn't play nicely with external stylesheets. Handles tables nicely but nothing like syntax highlighting.

Textdown

A simple, Chrome plugin for editing, conversion, and preview. Saves to browser cache; best for quick work.

Github-Flavored Markdown Editor

Has most of the fancy features of Markdown (syntax highlighting, tables. No math equations, though). Note that applying external sheets affects the entire pane, not just the markdown side.

Pandoc

A neat little conversion tool that can be used to convert .md files to just about anything, really. It can also be used to convert just about anything else to anything else. See the Pandoc Demo section for more details.

Markdown here

A neat little plugin that lets you write in Markdown, then convert to html in many email browsers, blog interfaces, etc.! Has the most comprehensive md function library that I could find.

Additional Markdown Resources

5. Pandoc Demo

Pandoc allows you to convert Markdown into many other formats. It is a command line tool. So it's ugly, and a little tricky. But if you become a Markdown user, it's worth the trouble learning how to use it.

A Microsoft doc

pandoc markpresnotes.md -o mark.doc

An html page

pandoc markpresnotes.md -o mark.html

A PDF

pandoc markpresnotes.md -o mark.pdf

A simple slidy web slideshow

pandoc -t slidy -s markpresnotes.md -o markslidy.html

Pandoc allows for modification of the css and templates, so it's endlessly customizable.

Screencast

6. Useful Stuff

Markdown Cheat Sheet

Markdown Cheat Sheet - for printing

Markdown workshop

A tutorial for graduate students

Simple markdown page for an example