Introduction

Malt is a multi-template rendering framework. It provides two convenient interfaces for working with backend template systems. The first is a functional interface via `Malt.render` method. And the second is an object-oriented interface that can be easily constructed via the `Malt.file` or `Malt.text` methods.

Formats

We have created a set of sample documents in the samples directory. We will take each format in turn.

  formats = %w{erb liquid}

Included with the format samples are files containing the expected results of each rendering.

  expected_output = {}

  formats.each do |format|
    expected_output[format] = File.read("qed/samples/output-#{format}.txt")
  end

The data to inject into the formats that interpolate, is also stored in the samples folder.

  data = YAML.load(File.new('qed/samples/data.yml'))

Now we can render each of thes formats, and verify we get the expected result.

  formats.each do |format|
    output = Malt.render(:file=>"qed/samples/sample.#{format}", :format=>format, :data=>data)
    output.assert == expected_output[format]
  end

Notice that formats the do not use interpolation data simply ignore it even if it is given.

We can also handle the files in a more object-oriented manner.

  formats.each do |format|
    object = Malt.file("qed/samples/sample.#{format}", :format=>format)
    output = object.render(data)
    output.assert == expected_output[format]
  end

Formats

Malt support a wide variety of markup and template systems.

Malt provides two distinct APIs for rendering each format —a single-point-of-entry functional interface, `Malt.render`, and an object-oriented interface where by each format is represented by a document class.

RDoc

Lets say we have a RDoc document called ‘test.rdoc’ containing:

  = Example

  This is an example of RDoc rendering.

We can convert rdoc documents to html easily via the univeral render function.

  html = Malt.render(:file=>'tmp/test.rdoc')

  html.assert.include?('<h1>Example</h1>')

Malt recognizes the type of file by the ’.rdoc’ extension and renders it using the default redering engine (in this case RDoc itself). By default the engine renders to HTML, so we did not need to specify the output :format option to the render method.

If we have a file that has a different extension, but is in fact an RDoc document, we can inform Malt.

Lets say we have an RDoc document called ‘test.txt’ containing:

  = Example

  This is an example of RDoc rendering.

We can inform Malt as the actual type using the `:type` option.

  html = Malt.render(:file=>'tmp/test.txt', :type=>:rdoc)

  html.assert.include?('<h1>Example</h1>')

Alternately we can use the object-oriented interface. Again, lets say we have an RDoc document called ‘test.rdoc’ containing …

  = Example

  This is an example of RDOC rendering.

Then we can use the `Malt.file` method to instantiate an RDoc object.

  rdoc = Malt.file('tmp/test.rdoc')

We will notice that the output is an instance of Malt::Formats::HTML.

  rdoc.class.assert == Malt::Format::RDoc

While we could have used `Malt::Formats::RDoc.new` to create the object directly, Malt provides the #file, as well as #text, methods for convience. We can convert the rdoc to html with the #to_html method.

  html = rdoc.to_html

Again notice that the output is an instance of Malt::Format::HTML.

  html.class.assert == Malt::Format::HTML

And that by calling #to_s we can get the rendered HTML document.

  html.to_s.assert.include?('<h1>Example</h1>')

We can convert rdoc documents to html very easily.

  rdoc = Malt.file('tmp/test.rdoc')

  html = rdoc.to_html

First we will notice that the output is an instance of Malt::Format::HTML.

  html.class.assert == Malt::Format::HTML

And that by calling #to_s we can get the rendered HTML document.

  html.to_s.assert.include?('<h1>Example</h1>')

Or we can convert the RDoc document directly to HTML via the #html method.

  out = rdoc.html

  out.assert.include?('<h1>Example</h1>')

Textile

Malt supports Textile via RedCloth.

Lets say we have a Textile document called ‘test.tt’ containing …

  h1. Example

  This is an example of Textile rendering.

We can redner the textile document via the universal render function. Textile documents are recognized by the .textile or .tt extension.

  html = Malt.render(:file=>'tmp/test.tt')

  html.assert.include?('<h1>Example</h1>')

Malt supports Textile via either the RedCloth or the _ backend.

Lets say we have an Textile document called ‘test.tt’ containing …

  h1. Example

  This is an example of Textile rendering.

We can access the file via the Malt.file method. Textile documents are recognized by the .textile or .tt extension.

  tile = Malt.file('tmp/test.tt')

We can the convert the document to a Malt Html object via the #to_html method.

  html = tile.to_html

Notice that the output is an instance of Malt::Format::HTML.

  html.class.assert == Malt::Format::HTML

And that by calling #to_s we can get the rendered HTML document.

  html.to_s.assert.include?('<h1>Example</h1>')

Or we can convert the document directly to HTML via the #html method.

  out = tile.html

  out.assert.include?('<h1>Example</h1>')

Markdown

Malt supports Markdown via either the RDiscount, BlueCloth or Kramdown backends.

Lets say we have a Markdown document called ‘test.md’ containing …

  # Example

  This is an example of Markdown rendering.

Markdown documents are recognized by the .markdown or .md file extensions.

  html = Malt.render(:file=>'tmp/test.md')

  html.assert.include?('<h1>Example</h1>')

By default teh RDiscount library is used to render markdown documents, but Malt supports BlueCloth and Kramdown as well. These case be used by setting the :engine option.

  html = Malt.render(:file=>'tmp/test.md', :engine=>:bluecloth)

And as we can see the document rendered as expected.

  html.assert.include?('<h1>Example</h1>')

And using the Kramdown library,

  html = Malt.render(:file=>'tmp/test.md', :engine=>:kramdown)

We can see the document rendered as well, though notice that Kramdown provides some bonus features compared to the other rendering engines.

  html.assert.include?('<h1 id="example">Example</h1>')

Malt supports Markdown via either the RDiscount, BlueCloth or Kramdown backends.

Lets say we have an Markdown document called ‘test.md’ containing …

  # Example

  This is an example of Markdown rendering.

We can access the file via the Malt.file method. Markdown documents are recognized by the .markdown or .md file extensions.

  mark = Malt.file('tmp/test.md')

We can the convert the document to a Malt Html object via the #to_html method.

  html = mark.to_html

Notice that the output is an instance of Malt::Format::HTML.

  html.class.assert == Malt::Format::HTML

And that by calling #to_s we can get the rendered HTML document.

  html.to_s.assert.include?('<h1>Example</h1>')

Or we can convert the document directly to HTML via the #html method.

  out = mark.html

  out.assert.include?('<h1>Example</h1>')

ERB

Malt supports ERB via the ERB and Erubis engines.

Lets say we have a ERB document called ‘test.erb’ containing …

  <h1>Example <%= title %></h1>

  <p>This is an example of ERB template.</p>

We can render erb documents via the render method, as we can any format. However, becuase ERB if a template format and not just a markup syntax, we need to also provide the render methods with data for interpolation into the ERB document.

  data = { :title=>"Document" }

  html = Malt.render(:file=>'tmp/test.erb', :data=>data)

And as we can see the document rendered as expected.

  html.assert.include?('<h1>Example Document</h1>')

ERB doesn’t actually care what format the document is rendered as. The template could have been any text file what so ever, so using the `:format` option would have no effect here.

By default the common ERB library is used to render erb documents. By setting the :engine option, Erubis can be used instead.

  html = Malt.render(:file=>'tmp/test.erb', :data=>data, :engine=>:erubis)

And as we can see the document rendered as expected.

  html.assert.include?('<h1>Example Document</h1>')

Malt supports template engines as well as formats.

Lets say we have an ERB document called ‘test.erb’ containing …

  <h1>Example <%= title %></h1>

  <p>This is an example of ERB template.</p>

We can render erb documents to any format we wish.

  erb = Malt.file('tmp/test.erb')

  html = erb.to_html(:title=>"Document")

We will notice that the output is an instance of Malt::Format::HTML.

  html.class.assert == Malt::Format::HTML

And that by calling #to_s we can get the rendered HTML document.

  html.to_s.assert.include?('<h1>Example Document</h1>')

Or we can convert the document directly to HTML via the #html method.

  out = erb.html(:title=>"Alternate")

  out.assert.include?('<h1>Example Alternate</h1>')

ERB doesn’t actually care what format the document is rendered as.

Liquid

Lets say we have a Liquid document called ‘test.liquid’ containing:

  <h1>Example {{ title }}</h1>

  <p>This is an example of a Liquid template.</p>

We can render liquid documents via the render method, as we can any format. However, becuase Liquid is a template format and not just a markup syntax, we need to also provide the render function with data for interpolation into the liquid document.

  data = { :title=>"Document" }

  html = Malt.render(:file=>'tmp/test.liquid', :data=>data)

  html.assert.include?('<h1>Example Document</h1>')

Liquid doesn’t actually care what format the document is rendered as, since it is purely a template engine that can be applied to any other format. Lets say we have a Liquid document called ‘test.liquid’ containing …

  <h1>Example {{ title }}</h1>

  <p>This is an example of a Liquid template.</p>

We can render erb documents to any format we wish.

  liq = Malt.file('tmp/test.liquid')

  html = liq.to_html(:title=>"Document")

We will notice that the output is an instance of Malt::Format::HTML.

  html.class.assert == Malt::Format::HTML

We will notice that the output is an instance of Malt::Format::HTML.

  html.class.assert == Malt::Format::HTML

Then by calling #to_s we can get the rendered HTML document.

  html.to_s.assert.include?('<h1>Example Document</h1>')

Or we can convert the document directly to HTML via the #html method.

  out = liq.html(:title=>"Alternate")

  out.assert.include?('<h1>Example Alternate</h1>')

Liquid doesn’t actually care what format the document is rendered as, since it is purely a template engine that can be applied to any format.

Haml

Lets say we have a Haml document called ‘test.haml’ containing:

  %h1== Example #{title}
  %p This is an example of a Haml template.

We can render Haml documents via the render method, as we can any format. While it might not appear as such on first glance, Haml is actually a template format and not just a markup language, so we need to also provide the render function with data for interpolation into the Haml document.

  data = { :title=>"Document" }

  html = Malt.render(:file=>'tmp/test.haml', :data=>data)

  html.assert.include?('<h1>Example Document</h1>')

We can get a hold of the Haml document via the Malt.file function.

  haml = Malt.file('tmp/test.haml')

  haml.class.assert == Malt::Format::Haml

We can convert Haml documents to html very easily.

  data = {:title => "Document"}

  html = haml.to_html(data)

First we will notice that the output is an instance of Malt::Format::HTML.

  html.class.assert == Malt::Format::HTML

And that by calling #to_s we can get the rendered HTML document.

  html.to_s.assert.include?('<h1>Example Document</h1>')

Or we can convert the Haml document directly to HTML via the #html method.

  out = haml.html(data)

  out.assert.include?('<h1>Example Document</h1>')

RagTag

Lets say we have a Rtals document called ‘test.rt’ containing:

  <html>
  <body>
    <h1>Example <span replace="title">DUMMY</span></h1>
    <p>This is an example of a RagTag template.</p>
  </body>
  </html>

We can render Rtal documents via the render method, as we can any format.

  data = { :title=>"Document" }

  html = Malt.render(:file=>'tmp/test.rt', :data=>data)

  html.assert.include?('<h1>Example Document</h1>')

Radius

Lets say we have a Radius document called ‘test.radius’ containing:

  <h1>Example <r:title /></h1>
  <p>This is an example of a Radius template.</p>

We can render Radius documents via the render method, as we can any format.

  data = {:title=>"Document"}

  html = Malt.render(:file=>'tmp/test.radius', :data=>data, :tag_prefix=>'r')

  html.assert.include?('<h1>Example Document</h1>')

We can get a hold of the Radius document via the Malt.file function.

  radi = Malt.file('tmp/test.radius', :tag_prefix=>'r')

  radi.class.assert == Malt::Format::Radius

Notice here we have passed an option to the file constructor. This option is passed on the underlying Radius.new method. Now we can convert Radius documents to HTML documents via #to_html.

  data = {:title => "Document"}

  html = radi.to_html(data)

First we will notice that the output is an instance of Malt::Format::HTML.

  html.class.assert == Malt::Format::HTML

And that by calling #to_s we can get the rendered HTML document.

  html.to_s.assert.include?('<h1>Example Document</h1>')

Or we can convert the Radius document directly to HTML via the #html method.

  out = radi.html(data)

  out.assert.include?('<h1>Example Document</h1>')

Tenjin

While Tenjin is generally intended to be used to render HTML documents, it is a general purpose template format that can be used for any type of document. For these uses, the Tenjin file extension is ’.tenjin’.

Lets say we have a Tenjin document called ‘test.tenjin’ containing:

  Hello #{@name}!

We can render the document via #render.

  data = { :name=>'World', :items=>['A','B','C'] }

  @text = Malt.render(:file=>'tmp/test.tenjin', :data=>data)

And we can verify that @text is:

  Hello World!

We can get a OOP interface tothe Tenjin document via the Malt.file function.

  tenjin = Malt.file('tmp/test.tenjin')

  tenjin.class.assert == Malt::Format::Tenjin

Since Tenjin is aa general pupose template foramt, we can convert Tenjin documents to any format we wish. For instance we can convert our example to a Text documents via #to_txt.

  data = { :name=>'World', :items=>['<AAA>', 'B&B', '"CCC"'] }

  text = tenjin.to_txt(data)

First we will notice that the output is an instance of `Malt::Format::Text`.

  text.class.assert == Malt::Format::Text

And that by calling #to_s we can get the rendered Text document.

  text.to_s.assert.include?('Hello World!')

Or we can convert the Tenjin document directly to text via the #txt method.

  out = tenjin.txt(data)

  out.assert.include?('Hello World!')

RBHTML

Tenjin is a general purpose template language with support for multiple languages including Ruby. The variation of Tenjin for Ruby, called rbTenjin, defines a document format with an extension of `.rbhtml`.

Lets say we have a Tenjin document called ‘test.rbhtml’ containing:

  Hello #{@name}!
  <ul>
  <?rb for item in @items ?>
   <li>${item}</li>
  <?rb end ?>
  </ul>

We can render the document via #render.

  data = { :name=>'World', :items=>['<AAA>', 'B&B', '"CCC"'] }

  @html = Malt.render(:file=>'tmp/test.rbhtml', :data=>data)

And we can verify that @html is:

  Hello World!
  <ul>
   <li>&lt;AAA&gt;</li>
   <li>B&amp;B</li>
   <li>&quot;CCC&quot;</li>
  </ul>

We can get a hold of the RBHTML document via the Malt.file function.

  rbhtml = Malt.file('tmp/test.rbhtml')

  rbhtml.class.assert == Malt::Format::RBHTML

We can convert RBHTML documents to HTML documents via #to_html.

  data = { :name=>'World', :items=>['<AAA>', 'B&B', '"CCC"'] }

  html = rbhtml.to_html(data)

First we will notice that the output is an instance of Malt::Format::HTML.

  html.class.assert == Malt::Format::HTML

And that by calling #to_s we can get the rendered HTML document.

  html.to_s.assert.include?('Hello World!')

Or we can convert the RBHTML document directly to HTML via the #html method.

  out = rbhtml.html(data)

  out.assert.include?('Hello World!')

Sass

Lets say we have a Sass document called ‘test.sass’ containing:

  $blue: #3bbfce
  $margin: 16px

  .content-navigation
    border-color: $blue
    color: darken($blue, 9%)

  .border
    padding: $margin / 2
    margin: $margin / 2
    border-color: $blue

We can render the Sass document via #render.

  @css = Malt.render(:file=>'tmp/test.sass')

And we can verify that @css is the expected CSS:

  .content-navigation {
    border-color: #3bbfce;
    color: #2ca2af; }

  .border {
    padding: 8px;
    margin: 8px;
    border-color: #3bbfce; }

We can also get a hold of the Sass document via the Malt.file function.

  sass = Malt.file('tmp/test.sass')

  sass.class.assert == Malt::Format::Sass

We can convert the Sass document to a CSS document via the #to_css method.

  css = sass.to_css

We can see that the output is an instance of Malt::Format::HTML.

  css.class.assert == Malt::Format::CSS

And that by calling #to_s we can get the rendered CSS document.

  css.to_s.assert.include?('border-color: #3bbfce;')

Or we can convert the Sass document directly to CSS via the #css method.

  out = sass.css

  out.assert.include?('border-color: #3bbfce;')

SCSS

Lets say we have a SCSS document called ‘test.scss’ containing:

  $blue: #3bbfce;
  $margin: 16px;

  .content-navigation {
    border-color: $blue;
    color:
      darken($blue, 9%);
  }

  .border {
    padding: $margin / 2;
    margin: $margin / 2;
    border-color: $blue;
  }

We can render the Sass document via #render.

  @css = Malt.render(:file=>'tmp/test.scss')

And we can verify that @css is the expected CSS:

  .content-navigation {
    border-color: #3bbfce;
    color: #2ca2af; }

  .border {
    padding: 8px;
    margin: 8px;
    border-color: #3bbfce; }

We can also get a hold of the SCSS document via the Malt.file function.

  scss = Malt.file('tmp/test.scss')

  scss.class.assert == Malt::Format::SCSS

We can convert the SCSS document to a CSS document via the #to_css method.

  css = scss.to_css

We can see that the output is an instance of Malt::Format::SCSS.

  css.class.assert == Malt::Format::CSS

And that by calling #to_s we can get the rendered CSS document.

  css.to_s.assert.include?('border-color: #3bbfce;')

Or we can convert the SCSS document directly to CSS via the #css method.

  out = scss.css

  out.assert.include?('border-color: #3bbfce;')

LESS

Lets say we have a LESS document called ‘test.less’ containing:

  @brand_color: #4D926F;
  #header {
    color: @brand_color;
  }
  h2 {
    color: @brand_color;
  }

We can render it via Malt with #render.

  @css = Malt.render(:file=>'tmp/test.less')

And we can verify that @css is:

  #header, h2 { color: #4d926f; }

Look how concise that is. LESS is pretty slick.

We can also get a hold of the LESS document via the Malt.file function.

  less = Malt.file('tmp/test.less')

  less.class.assert == Malt::Format::LESS

We can convert the LESS document to a CSS document via the #to_css method.

  css = less.to_css

We can see that the output is an instance of Malt::Format::HTML.

  css.class.assert == Malt::Format::CSS

And that by calling #to_s we can get the rendered CSS document.

  css.to_s.assert.include?('#header, h2 { color: #4d926f; }')

Or we can convert the LESS document directly to CSS via the #css method.

  out = less.css

  out.assert.include?('#header, h2 { color: #4d926f; }')

Ruby

It may not seem obvious at first, but Ruby itself can be used as a template system.

Lets say we have a Ruby document called ‘test.rb’ containing:

  "<h1>Example #{ title }</h1>\n" +
  "<p>This is an example of Ruby rendering.</p>"

We can run this Ruby script thru Malt’s render function.

  data = {:title => 'Document'}

  html = Malt.render(:file=>'tmp/test.rb', :data=>data)

Whatever was the final result of evaluating the Ruby script, converted to a string via #to_s, will be the result of the rendering.

  html.assert.include?('<h1>Example Document</h1>')

We can get a hold of the Ruby template via the Malt.file function.

  ruby = Malt.file('tmp/test.rb')

  ruby.class.assert == Malt::Format::Ruby

Ruby is a universal template format, so it can be converted to any other format (even if it is not really that format).

  data = {:title => "Document"}

  html = ruby.to_html(data)

First we will notice that the output is an instance of Malt::Format::HTML.

  html.class.assert == Malt::Format::HTML

And that by calling #to_s we can get the rendered HTML document.

  html.to_s.assert.include?('<h1>Example Document</h1>')

Or we can convert the Ruby document directly to HTML via the #html method.

  out = ruby.html(data)

  out.assert.include?('<h1>Example Document</h1>')

Markaby

Lets say we have a Markaby document called ‘test.markaby’ containing:

  html do
    h1 "Example #{@title}"
    p "This is an example of a Maraby template."
  end

Notice the use of the instance variable. Markaby templates must use instance variables for data rendering in order to avoid ambiguity with the markup syntax itself.

We can render Markaby documents via the render method, as we can any format. Since Markaby is a template format and not just a markup syntax, so we need to also provide the render function with data for interpolation into the Markaby document.

  data = { :title=>"Document" }

  html = Malt.render(:file=>'tmp/test.markaby', :data=>data)

  html.assert.include?('<h1>Example Document</h1>')

We can get a hold of the Markaby document via the Malt.file function.

  markaby = Malt.file('tmp/test.markaby')

  markaby.class.assert == Malt::Format::Markaby

We can convert Markaby documents to html very easily.

  data = {:title => "Document"}

  html = markaby.to_html(data)

First we will notice that the output is an instance of Malt::Format::HTML.

  html.class.assert == Malt::Format::HTML

And that by calling #to_s we can get the rendered HTML document.

  html.to_s.assert.include?('<h1>Example Document</h1>')

Or we can convert the Markaby document directly to HTML via the #html method.

  out = markaby.html(data)

  out.assert.include?('<h1>Example Document</h1>')

Mustache

Lets say we have a Mustache document called ‘test.mustache’ containing:

  <h1>Example {{ title }}</h1>

  <p>This is an example of a Mustache template.</p>

We can render mustache documents via the render method, as we can any format. However, becuase Mustache is a template format and not just a markup syntax, we need to also provide the render function with data for interpolation into the mustache document.

  data = { :title=>"Document" }

  html = Malt.render(:file=>'tmp/test.mustache', :data=>data)

  html.assert.include?('<h1>Example Document</h1>')

Mustache doesn’t actually care what format the document is rendered as, since it is purely a template engine that can be applied to any other format. Lets say we have a Mustache document called ‘test.mustache’ containing …

  <h1>Example {{ title }}</h1>

  <p>This is an example of a Mustache template.</p>

We can render erb documents to any format we wish.

  liq = Malt.file('tmp/test.mustache')

  html = liq.to_html(:title=>"Document")

We will notice that the output is an instance of Malt::Format::HTML.

  html.class.assert == Malt::Format::HTML

We will notice that the output is an instance of Malt::Format::HTML.

  html.class.assert == Malt::Format::HTML

Then by calling #to_s we can get the rendered HTML document.

  html.to_s.assert.include?('<h1>Example Document</h1>')

Or we can convert the document directly to HTML via the #html method.

  out = liq.html(:title=>"Alternate")

  out.assert.include?('<h1>Example Alternate</h1>')

Mustache doesn’t actually care what format the document is rendered as, since it is purely a template engine that can be applied to any format.

Markdown: Basics

Getting the Gist of Markdown's Formatting Syntax

This page offers a brief overview of what it's like to use Markdown. The syntax page provides complete, detailed documentation for every feature, but Markdown should be very easy to pick up simply by looking at a few examples of it in action. The examples on this page are written in a before/after style, showing example syntax and the HTML output produced by Markdown.

It's also helpful to simply try Markdown out; the Dingus is a web application that allows you type your own Markdown-formatted text and translate it to XHTML.

Note: This document is itself written using Markdown; you can see the source for it by adding '.text' to the URL.

Paragraphs, Headers, Blockquotes

A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. (A blank line is any line that looks like a blank line -- a line containing nothing but spaces or tabs is considered blank.) Normal paragraphs should not be indented with spaces or tabs.

Markdown offers two styles of headers: Setext and atx. Setext-style headers for <h1> and <h2> are created by "underlining" with equal signs (=) and hyphens (-), respectively. To create an atx-style header, you put 1-6 hash marks (#) at the beginning of the line -- the number of hashes equals the resulting HTML header level.

Blockquotes are indicated using email-style '>' angle brackets.

Markdown:

A First Level Header
====================

A Second Level Header
---------------------

Now is the time for all good men to come to
the aid of their country. This is just a
regular paragraph.

The quick brown fox jumped over the lazy
dog's back.

### Header 3

> This is a blockquote.
> 
> This is the second paragraph in the blockquote.
>
> ## This is an H2 in a blockquote

Output:

<h1>A First Level Header</h1>

<h2>A Second Level Header</h2>

<p>Now is the time for all good men to come to
the aid of their country. This is just a
regular paragraph.</p>

<p>The quick brown fox jumped over the lazy
dog's back.</p>

<h3>Header 3</h3>

<blockquote>
    <p>This is a blockquote.</p>

    <p>This is the second paragraph in the blockquote.</p>

    <h2>This is an H2 in a blockquote</h2>
</blockquote>

Phrase Emphasis

Markdown uses asterisks and underscores to indicate spans of emphasis.

Markdown:

Some of these words *are emphasized*.
Some of these words _are emphasized also_.

Use two asterisks for **strong emphasis**.
Or, if you prefer, __use two underscores instead__.

Output:

<p>Some of these words <em>are emphasized</em>.
Some of these words <em>are emphasized also</em>.</p>

<p>Use two asterisks for <strong>strong emphasis</strong>.
Or, if you prefer, <strong>use two underscores instead</strong>.</p>

Lists

Unordered (bulleted) lists use asterisks, pluses, and hyphens (*, +, and -) as list markers. These three markers are interchangable; this:

*   Candy.
*   Gum.
*   Booze.

this:

+   Candy.
+   Gum.
+   Booze.

and this:

-   Candy.
-   Gum.
-   Booze.

all produce the same output:

<ul>
<li>Candy.</li>
<li>Gum.</li>
<li>Booze.</li>
</ul>

Ordered (numbered) lists use regular numbers, followed by periods, as list markers:

1.  Red
2.  Green
3.  Blue

Output:

<ol>
<li>Red</li>
<li>Green</li>
<li>Blue</li>
</ol>

If you put blank lines between items, you'll get <p> tags for the list item text. You can create multi-paragraph list items by indenting the paragraphs by 4 spaces or 1 tab:

*   A list item.

    With multiple paragraphs.

*   Another item in the list.

Output:

<ul>
<li><p>A list item.</p>
<p>With multiple paragraphs.</p></li>
<li><p>Another item in the list.</p></li>
</ul>

Links

Markdown supports two styles for creating links: inline and reference. With both styles, you use square brackets to delimit the text you want to turn into a link.

Inline-style links use parentheses immediately after the link text. For example:

This is an [example link](http://example.com/).

Output:

<p>This is an <a href="http://example.com/">
example link</a>.</p>

Optionally, you may include a title attribute in the parentheses:

This is an [example link](http://example.com/ "With a Title").

Output:

<p>This is an <a href="http://example.com/" title="With a Title">
example link</a>.</p>

Reference-style links allow you to refer to your links by names, which you define elsewhere in your document:

I get 10 times more traffic from [Google][1] than from
[Yahoo][2] or [MSN][3].

[1]: http://google.com/        "Google"
[2]: http://search.yahoo.com/  "Yahoo Search"
[3]: http://search.msn.com/    "MSN Search"

Output:

<p>I get 10 times more traffic from <a href="http://google.com/"
title="Google">Google</a> than from <a href="http://search.yahoo.com/"
title="Yahoo Search">Yahoo</a> or <a href="http://search.msn.com/"
title="MSN Search">MSN</a>.</p>

The title attribute is optional. Link names may contain letters, numbers and spaces, but are not case sensitive:

I start my morning with a cup of coffee and
[The New York Times][NY Times].

[ny times]: http://www.nytimes.com/

Output:

<p>I start my morning with a cup of coffee and
<a href="http://www.nytimes.com/">The New York Times</a>.</p>

Images

Image syntax is very much like link syntax.

Inline (titles are optional):

![alt text](/path/to/img.jpg "Title")

Reference-style:

![alt text][id]

[id]: /path/to/img.jpg "Title"

Both of the above examples produce the same output:

<img src="/path/to/img.jpg" alt="alt text" title="Title" />

Code

In a regular paragraph, you can create code span by wrapping text in backtick quotes. Any ampersands (&) and angle brackets (< or >) will automatically be translated into HTML entities. This makes it easy to use Markdown to write about HTML example code:

I strongly recommend against using any `<blink>` tags.

I wish SmartyPants used named entities like `&mdash;`
instead of decimal-encoded entites like `&#8212;`.

Output:

<p>I strongly recommend against using any
<code>&lt;blink&gt;</code> tags.</p>

<p>I wish SmartyPants used named entities like
<code>&amp;mdash;</code> instead of decimal-encoded
entites like <code>&amp;#8212;</code>.</p>

To specify an entire block of pre-formatted code, indent every line of the block by 4 spaces or 1 tab. Just like with code spans, &, <, and > characters will be escaped automatically.

Markdown:

If you want your page to validate under XHTML 1.0 Strict,
you've got to put paragraph tags in your blockquotes:

    <blockquote>
        <p>For example.</p>
    </blockquote>

Output:

<p>If you want your page to validate under XHTML 1.0 Strict,
you've got to put paragraph tags in your blockquotes:</p>

<pre><code>&lt;blockquote&gt;
    &lt;p&gt;For example.&lt;/p&gt;
&lt;/blockquote&gt;
</code></pre>

RDoc Format

This is RDoc formatted markup.

one
two
three

Table of Contents

Introduction

Formats

Formats

RDoc

Textile

Markdown

ERB

Liquid

Haml

RagTag

Radius

Tenjin

RBHTML

Sass

SCSS

LESS

Ruby

Markaby

Mustache

Markdown: Basics

Getting the Gist of Markdown's Formatting Syntax

Paragraphs, Headers, Blockquotes

Phrase Emphasis

Lists

Links

Images

Code

RDoc Format