Jeromy Anglim's Blog: Psychology and Statistics


Friday, November 12, 2010

Getting Started with Markdown: Benefits, Installation, Learning, and Conversion

I've recently adopted Markdown as a markup language for editing my blog posts. This post discusses (a) the benefits of Markdown, (b) installing a Markdown editor, (c) learning Markdown, and (d) converting between formats.

Overview

Great features of Markdown are:

  • It's plain text (e.g., support for version control, create with code)
  • It's simple to learn and use
  • The source is highly readable (much more so than HTML or LaTeX; and arguably more so than other markup languages)
  • It's quicker to type than HTML
  • It's easy to convert to other formats
  • Several websites such as Stack Exchange and Github use it
  • HTML code can be interspersed when features such as tables are not supported

It's not for everything, but it's a good tool for certain tasks. I'm still exploring the options, but in the case of blog posts and readme files it works well.

Installation

I chose to install the Markdown Editor plugin for Eclipse developed by Daniel Winterstein. Cool features include:

  • Outline View
  • Syntax highlighting
  • Markdown HTML Preview
  • Integration with Eclipse

Installation instructions can be found on the winterwell website.

Learning the Syntax

The markup is simple to learn. I first installed the Markdown Editor in Eclipse
and associated .md files with the Markdown editor.

I then:

  1. created a file called test.md and opened it in the Markdown editor in Eclipse
  2. opened the Markdown HTML Preview: Window -- Show View -- Other -- Markdown -- Markdown HTML Preview
  3. worked through the Markdown syntax guide creating simple proof of concept examples, bouncing between the Markdown Editor and the Markdown HTML Preview.

Conversion

Markdown to HTML

Using the Eclipse Markdown plugin, a HTML version of the Markdown file can be obtained in several ways.

  • Right click the Markdown HTML Preview and click "View Source"
  • When in the Markdown editor, go to File -- Export HTML. This creates a HTML version of the file

Other options

Pandoc appears to be a good option for converting between document formats such as Markdown, LaTeX, RTF, PDF, OpenDocument, and more.

Copy of this Post in Markdown

The code below shows the Markdown used to create this post (except of course for the Markdown shown below).

I've recently adopted Markdown as a markup language for editing my blog posts.
This post discusses 
(a) the benefits of Markdown,
(b) installing a Markdown editor,
(c) learning Markdown, and
(d) converting between formats.

<!-- more -->
### Overview

Great features of Markdown are:

* It's plain text (e.g., support for version control, create with code)  
* It's simple to learn and use
* The source is highly readable (much more so than HTML or LaTeX; and arguably more so than other markup languages)
* It's quicker to type than HTML 
* It's easy to convert to other formats
* Several websites such as Stack Exchange and Github use it
* HTML code can be interspersed when features such as tables are not supported 

It's not for everything, but it's a good tool for certain tasks.
I'm still exploring the options, but in the case of blog posts and readme files it works well.


### Installation
I chose to install the Markdown Editor plugin for Eclipse developed by Daniel Winterstein. 
Cool features include:

* Outline View
* Syntax highlighting
* Markdown HTML Preview
* Integration with Eclipse

Installation instructions can be found on the [winterwell] website.

[winterwell]: http://www.winterwell.com/software/markdown-editor.php 


### Learning the Syntax
The markup is simple to learn.
I first installed the Markdown Editor in Eclipse  
 and associated `.md` files with the Markdown editor.

I then:

1. created a file called `test.md` and opened it in the Markdown editor in Eclipse
2. opened the Markdown HTML Preview: 
`Window -- Show View -- Other -- Markdown -- Markdown HTML Preview`
3. worked through the [Markdown syntax guide][msg]
  creating simple proof of concept examples, bouncing between
  the Markdown Editor and the Markdown HTML Preview.

[msg]: http://daringfireball.net/projects/markdown/syntax


### Conversion
#### Markdown to HTML
Using the Eclipse Markdown plugin, a HTML version of the Markdown file
 can be obtained in several ways.

* Right click the Markdown HTML Preview and click "View Source"
* When in the Markdown editor, go to File -- Export HTML. 
  This creates a HTML version of the file

#### Other options
[Pandoc] appears to be a good option for converting between document 
 formats such as Markdown, LaTeX, RTF, PDF, OpenDocument, and more. 

[pandoc]: http://johnmacfarlane.net/pandoc/