% Document Your World With Markdown
% Sean Boisen, [Faithlife Corporation](https://faithlife.com/about)
% Slides online at [http://seanboisen.com/talks/2015/markdown](http://seanboisen.com/talks/2015/markdown) (eventually)

## Introduction
* About me
* Goals for this talk
	* What is Markdown and why should I use it?
	* How do I create Markdown?
	* What can I do with Markdown?

## What is Markdown?
* Markdown is 
	* a simple system 
	* for structuring plain text 
	* that covers just enough to meet the most common needs.

> "A designer knows he has achieved perfection not when there is nothing left to add, but when there is nothing left to take away." -- Antoine de Saint-Exupéry

## Why Markdown? 
* Text is the universal format.
* There is power in simplicity.
* Markdown emphasizes content and writing, with “just enough” formatting to avoid distraction.
* Creating with Markdown harnesses the value of a simple core + powerful transformations

> "What information consumes is rather obvious: it consumes the attention of its recipients. Hence a wealth of information creates a poverty of attention, and a need to allocate that attention efficiently among the overabundance of information sources that might consume it." -- Herbert Simon

## Markdown Example
Markdown is **great** for

* text and `code` formatting
* lists, links, images, and more

John Gruber says:

> "The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible." 

Using Markdown typically involves *both*:

1. Authoring text in a specific format
2. Converting Markdown to other formats

There's detailed [syntax documentation on the web](http://daringfireball.net/projects/markdown/syntax).

![Caption](markdown-icon.144x96.jpg "A Markdown icon")

## Markdown Example (Revealed)
Markdown is **great** for

* text and `code` formatting
* lists, links, images, and more

John Gruber says:

> "The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible." 

	Markdown is **great** for
	
	* text and `code` formatting
	* lists, links, images, and more
	
	John Gruber says:
	
	> "The overriding design goal for Markdown’s formatting syntax is to make it as readable as possible." 

## More Markdown Example (Revealed)
Using Markdown typically involves *both*:

1. Authoring text in a specific format
2. Converting Markdown to other formats

There's detailed [syntax documentation on the web](http://daringfireball.net/projects/markdown/syntax).

![Caption](markdown-icon.144x96.jpg "A Markdown icon")

	Using Markdown typically involves *both*:
	
	1. Authoring text in a specific format
	2. Converting Markdown to other formats
	
	There's detailed [syntax documentation on the web](http://daringfireball.net/projects/markdown/syntax).

	![Caption](markdown-icon.144x96.jpg "A Markdown icon")

## More Markdown Details
Alternative syntax:

	## Atx-style headers
	Setext-style Headers look underlined (= or -)
	=======================================
	
	Emphasis and strong can use *asterisks* or _underscores_
	Lists can use * or -

Hyperlinks:

	[An inline link](http://lnfw.org "LinuxFest") with title
	--------
	[A reference link][lnfw]
	...
	[lnfw]: http://lnfw.org "Linuxfest"
	--------
	[LinuxFest][] uses an implicit link
	...
	[LinuxFest]: http://lnfw.org

## Tools for Writing Markdown
* Your favorite text editor
* OS X: 
	* Long list at Slant: "[What is the best Markdown editor for OS X?](http://www.slant.co/topics/899/~what-is-the-best-markdown-editor-for-os-x)" 
	* My current favorite is [Lightpaper from ashokgelal.com](http://www.ashokgelal.com/lightpaper-for-mac/): WYSIWYG styling, preview pane
* Emacs: some styling, display as HTML
* Extras and plugins for emacs, vim, Notepad++, Sublime, Mac OS X services, many others

### Authoring Markdown in the Browser
* [StackEdit](https://stackedit.io/editor): author, publish, synchronize, import/export/  
* [Markdown: Dingus](http://daringfireball.net/projects/markdown/dingus) displays HTML source and preview

> "Rarely do more than three or four variables really count. Everything else is noise." -- Marty Whitman

## What You Can Make with It
* Single-page HTML
* Blog posts (Movable Type, BBEdit, Blossom)
* Other formats: PDF, .docx, Open Document, man page, LaTex, and many more
* HTML for presentations (Slide, S5, others)
* Static web sites
* E-books in ePub

> "Our life is frittered away by detail … simplify, simplify." -- Henry David Thoreau

## Tools for Converting Markdown
* [Gruber's Markdown script (Perl)](http://daringfireball.net/projects/markdown/)
* [Python Markdown][] 
* [pandoc][]: the "universal document converter"

![pandoc is a Swiss army knife](Swiss-army-knife.png "Pandoc is like a Swiss army knife")

## Create a Presentation
* [HTML Slidy](http://www.w3.org/Talks/Tools/Slidy2): a W3C tool using HTML+Javascript for presentations
* Javascript controls to display one slide at a time
* 2nd-level headings become individual slides
* CSS styling can be customized
* This presentation was made from Markdown!
`pandoc -s -S -t slidy -o markdown.html Markdown-talk.md`

> "The secret of concentration is elimination." -- Howard Hendricks

## Create a Website
* Make the structure yourself and convert pages from Markdown to HTML
* [jekyll][] (ruby): free hosting with Github Pages
* [PyKwiki](http://pykwiki.nullism.com/): blogging platform with searching

> "A great man is one sentence." -- Clare Boothe

## Make an eBook
* ePub is just a container with content, styling, TOC, etc.
* Substitute your own stylesheet, cover image, metadata, fonts
* [Creating an ebook with pandoc](http://pandoc.org/epub.html) shows how to generate an ePub for [Pro Git](https://progit.org/)

![](progit.jpg "Cover image for Pro Git book")

## What's Missing
* Tables
* Centering
* Fine control over size, layout

> “There is nothing so useless as doing efficiently that which should not be done at all.” -- Peter Drucker

## Variants and Relatives
* [MultiMarkdown](https://github.com/fletcher/MultiMarkdown/wiki/MultiMarkdown-Syntax-Guide) adds support for metadata, table, and more. 
* [AsciiDoc](http://www.methods.co.nz/asciidoc/):  looks less like plain text, and is less broadly used
* Wiki markup
* [reStructuredText](http://docutils.sourceforge.net/rst.html): popular for Python documentation
* [YAML][]: more like a data language

## For The Hardcore Geek
* [Python Markdown][] has an [extensions API](https://pythonhosted.org/Markdown/extensions/api.html)
* [pandoc][] (Haskell)

## Wrapping Up

* Simple core + powerful transformations = Win!

> "Besides the noble art of getting things done, there is the noble art of leaving things undone. The wisdom of life consists in the elimination of nonessentials." -- Lin Yutang

## More about me
* Twitter: [seanboisen](http://twitter.com/seanboisen)
* Websites: [SemanticBible](http://www.semanticbible.com/), [SeanBoisen.com](http://seanboisen.com/)
* Previous LinuxFest talks:
	* [From 0 to Website in 60 Minutes - With Django (2010)](http://semanticbible.com/other/talks/2010/linuxfestnw/main.html)
	* [Natural Language Processing in Python using NLTK (2008)](http://semanticbible.com/other/talks/2008/nltk/main.html)

[jekyll]: http://jekyllrb.com/docs/home/
[pandoc]: http://pandoc.org/
[Python Markdown]: https://pythonhosted.org/Markdown/
[YAML]: http://yaml.org/