kramdown 0.1.0

data/doc/installation.page

@@ -0,0 +1,90 @@
+---
+title: Download & Installation
+in_menu: true
+sort_info: 5
+---
+# Download & Installation
+
+## Compatibility Notes
+
+kramdown should work on any platform which supports Ruby. It has been successfully tested on the
+following platforms:
+
+* Linux with Ruby 1.8.6
+* Mac OSX with Ruby 1.8.6, 1.8.7, 1.9.1, 1.9.2-preview1 and jruby 1.4.0.
+
+See the platform specific installation notes for more information!
+
+
+## Platform Specific Installation Instructions
+
+### Linux
+
+There are a variety of Linux distributions out there with different package management systems. So we
+will focus on instructions for Ubuntu 9.04 here (which should probably also work for any recent
+Debian based distribution).
+
+After running the following commands, kramdown is installed and ready to use:
+
+    sudo aptitude install ruby rubygems
+    sudo gem1.8 install kramdown
+
+> You will also need to add `export PATH=$PATH:/var/lib/gems/1.8/bin` to your `~/.bashrc` because
+> this is the binary path the executable files get installed.
+
+
+### Mac OS X
+
+Mac OS X Snow Leopard comes with Ruby and Rubygems preinstalled. So installing kramdown is as easy
+as running:
+
+    sudo gem install kramdown
+
+
+### Windows
+
+You need to install Ruby first. This can easily be done by using the One-Click-Installer - just
+download the *latest* installation binary from the [files section][1] of the One-Click-Installer
+homepage and run it. After that open a command shell (select `Start -> Run...`, then enter `cmd` and
+click on `Ok`) and type in the following:
+
+    gem install kramdown
+
+[1]: http://rubyforge.org/frs/?group_id=167
+
+
+## Generic Installation Instructions
+
+
+### Using Rubygems
+
+If you are using Rubygems, installing the latest version of kramdown is as simple as executing
+
+    gem install kramdown
+
+
+### Manual Installation
+
+The latest version of kramdown can always be downloaded as `.tar.gz` or `.zip` from [its files
+section on Rubyforge](http://rubyforge.org/frs/?group_id=7403). After the download the package needs
+to be decompressed and then you can install kramdown using the included `setup.rb` installation
+method:
+
+    $ ruby setup.rb config
+    $ ruby setup.rb setup
+    $ ruby setup.rb install
+
+
+### Using the repository version
+
+kramdown uses git as its versioning system and kramdown's repository is hosted on GitHub. The
+repository always contains a clean state of the current development version of kramdown. To check
+out kramdown use the following command:
+
+     git clone git://github.com/gettalong/kramdown.git
+
+
+## Dependencies
+
+Since kramdown is written in Ruby, you just need the [Ruby interpreter](http://www.ruby-lang.org)
+versions 1.8.6, 1.8.7 or 1.9.1. There are no other dependencies.

data/doc/news.feed

@@ -0,0 +1,10 @@
+---
+title: kramdown News
+description: kramdown - a fast, pure Ruby Markdown+extensions converter
+site_url: http://kramdown.rubyforge.org/
+author: Thomas Leitner
+author_url: http://kramdown.rubyforge.org
+number_of_entries: 10
+rss: false
+entries: [news/*.html]
+

data/doc/news.page

@@ -0,0 +1,27 @@
+---
+title: News
+in_menu: true
+sort_info: 30
+--- pipeline:tags,blocks,fragments
+
+<h1>News</h1>
+
+<a href="{relocatable: news.atom}">Atom-Feed</a>
+
+<webgen:block name="newsdata" node="current" />
+
+--- name:newsdata pipeline:erb
+<%
+context.content_node.tree.node_access[:alcn].select do |na,no|
+   na =~ /\/news\/.+/ && no.is_file?
+end.collect {|na,no| no}.sort.reverse.each do |node|
+%>
+
+<div class='news-item'>
+<div class="news-date f-right">
+  Published on <%= node['created_at'].strftime("%A, %d %B %Y") %>
+</div>
+<%= context.render_block(:name => 'content', :chain => [node]) %>
+</div>
+
+<% end %>

data/doc/quickref.page

@@ -0,0 +1,474 @@
+---
+title: Quick Reference
+in_menu: true
+sort_info: 9
+---
+# Quick Reference
+
+Below are examples of all available structural elements that can be used in kramdown text. Note,
+that only the most basic syntax information is given. However, a link to the detailed syntax for
+each element is provided.
+
+kramdown has two main classes of elements: block and span level elements. Block level elements are
+used to create paragraphs, headers, lists and so on whereas span level elements are used to markup
+text phrases as emphasized, as a link and so on.
+
+All examples below feature the kramdown source, the converted HTML source and the output as it
+appears in the browser. This looks like this:
+
+{::nokramdown:}
+<div class="kdexample">
+<pre class="kdexample-before"><code>kramdown example code
+</code></pre>
+<pre class="kdexample-after-source"><code>Example code converted to HTML
+</code></pre>
+<div class="kdexample-after-live">
+Live browser view of example code
+</div>
+</div>
+<div class="clear"></div>
+{::nokramdown:}
+
+
+# Block Level Elements - Main Structural Elements
+
+## Paragraphs
+
+{::kdlink:: #paragraphs part="paragraphs"}
+
+Paragraphs are separated by one or more blank lines:
+
+{::kdexample:}
+The first paragraph.
+
+Another paragraph
+{::kdexample:}
+
+Explicit line breaks in a paragraph can be made by using two spaces or two backslashes at the end of a line:
+
+{::kdexample:}
+This is a paragraph  
+which contains a hard line break.
+{::kdexample:}
+
+
+## Headers
+
+{::kdlink:: #headers part="headers"}
+
+kramdown supports Setext style headers and atx style headers. A header must always be preceeded by a
+blank line except at the beginning of the document:
+
+{::kdexample:}
+First level header
+==================
+
+Second level header
+-------------------
+{::kdexample:}
+
+{::kdexample:}
+# H1 header
+
+## H2 header
+
+### H3 header
+
+#### H4 header
+
+##### H5 header
+
+###### H6 header
+{::kdexample:}
+
+If you set the option `auto_ids` to `true` (for example, by using the `kdoptions` extension, see
+[Extension Blocks](#extension-blocks)), then all headers are automatically given header IDs based on
+the header text:
+
+{::kdexample:}
+# A header without an ID
+
+{::kdoptions:: auto_ids="true"}
+
+# A header with an ID
+{::kdexample:}
+
+
+## Blockquotes
+
+{::kdlink:: #blockquotes part="blockquotes"}
+
+A blockquote is started using the `>` marker followed by an optional space; all following lines that
+are also started with the blockquote marker belong to the blockquote. You can use any block level
+elements inside a blockquote:
+
+{::kdexample:}
+> A sample blockquote.
+> >Nested blockquotes are
+> >also possible.
+>
+> ## Headers work too
+> This is the outer quote again.
+{::kdexample:}
+
+
+## Code Blocks
+
+{::kdlink:: #code-blocks part="code blocks"}
+
+kramdown supports two different code block styles. One uses lines indented with either four spaces
+or one tab whereas the other uses lines with tilde characters as delimiters -- therefore the content
+does not need to be indented:
+
+{::kdexample:}
+    This is a sample code block.
+
+    Continued here.
+{::kdexample:}
+
+{::kdexample:}
+~~~~~~
+This is also a code block.
+~~~
+Ending lines must have at least as
+many tildes as the starting line.
+~~~~~~~~~~~~
+{::kdexample:}
+
+
+## Horizontal Rules
+
+{::kdlink:: #horizontal-rules part="horizontal rules"}
+
+It is easy to insert a horizontal rule in kramdown: just use three or more asterisks, dashes or
+underscores, optionally separated by spaces or tabs, on an otherwise blank line:
+
+{::kdexample:}
+* * *
+
+\---
+
+  _  _  _  _
+
+---------------
+{::kdexample:}
+
+
+## Lists
+
+{::kdlink:: #lists part="lists"}
+
+kramdown supports ordered and unordered lists. Ordered lists are started by using a number followed
+by a period, a space and then the list item text. The content of a list item consists of block level
+elements. All lines which have the same indent as the text of the line with the list marker belong
+to the list item:
+
+{::kdexample:}
+1. This is a list item
+2. And another item
+2. And the third one
+   with additional. text
+{::kdexample:}
+
+As the content consists of block level elements you can do things like the following:
+
+{::kdexample:}
+1.  This is a list item
+
+    > with a blockquote
+
+    # And a header
+
+2.  Followed by another item
+{::kdexample:}
+
+Nested lists are also easy to create:
+
+{::kdexample:}
+1. Item one
+   1. sub item one
+   2. sub item two
+   3. sub item three
+2. Item two
+{::kdexample:}
+
+Lists can occur directly after other block level elements, however, there has to be at least one
+blank line if you want to follow a paragraph with a list:
+
+{::kdexample:}
+This is a paragraph.
+1. This is NOT a list.
+
+1. This is a list!
+{::kdexample:}
+
+Unordered lists are started by using an asterisk, a dash or a plus sign (they can be mixed) and a
+space. Apart from that unordered lists follow the same rules as ordered lists:
+
+{::kdexample:}
+* Item one
++ Item two
+- Item three
+{::kdexample:}
+
+
+## HTML elements
+
+kramdown allows you to use block level HTML tags (`div`, `p`, `pre`, ...) to markup whole blocks of
+text -- just start a line with a block level HTML tag. The content of a block level HTML tag is
+parsed by kramdown either as block level or span level text, depending on the tag:
+
+{::kdexample:}
+<div style="float: right">
+Something that stays right.
+</div>
+Normal text flow.
+<p>
+This can contain only *span* level elements.
+</p>
+{::kdexample:}
+
+
+## Block Attributes
+
+{::kdlink:: #block-inline-attribute-lists part="block IALs"}
+{::kdlink:: #attribute-list-definitions part="ALDs"}
+
+You can assign any attribute to a block level element. Just directly follow the block with a *block
+inline attribute list* (or short: block IAL). A block IAL consists of a left curly brace, followed
+by a colon, the attribute definitions and a right curly brace. Here is a simple example which sets the
+`title` attribute of a block quote:
+
+{::kdexample:}
+> A nice blockquote
+{: title="Blockquote title"}
+{::kdexample:}
+
+As one often wants to set one or more CSS classes on an element, there is an easy shortcut:
+
+{::kdexample:}
+> A nice blockquote
+{: .class1 .class2}
+{::kdexample:}
+
+A shortcut for setting the ID is also provided. Just prefix the ID with a hash symbol:
+
+{::kdexample:}
+> A nice blockquote
+{: #with-an-id}
+{::kdexample:}
+
+Sometimes one wants to use the same attributes for many elements. kramdown allows you to define the
+attributes in one place with an *attribute list definition* (or short: ALD) and just reference this
+definition in a block IAL. An ALD has the same structure as a block IAL but the colon has to be
+replace with a colon, the reference name and another colon. By just using the reference name as-is
+in a block IAL, one can include the attributes of the referenced ALD:
+
+{::kdexample:}
+{:refdef: .c1 #id .c2 title="title"}
+paragraph
+{: refdef}
+{::kdexample:}
+
+The order in a block IAL or ALD is important because later defined attributes overwrite (with the
+exception of the shortcut for CSS classes) prior defined attributes:
+
+{::kdexample:}
+{:refdef: .c1 #id .c2 title="title"}
+paragraph
+{: refdef .c3 title="t" #para}
+{::kdexample:}
+
+
+## Extension Blocks
+
+{::kdlink:: #extension-blocks part="extension blocks"}
+
+Extension blocks can be used to add custom behaviour to kramdown. For more information on how to do
+this have a look at the [API documentation]({relocatable: /rdoc/index.html}). kramdown comes with
+some built-in extensions for ignoring text (i.e. treating text as comment), for inserting arbitrary
+text into the output and for setting kramdown options.
+
+Here is an example that shows how to insert comments into text:
+
+{::kdexample:}
+This is a paragraph
+{::comment:}
+This is a comment which is
+completely ignored.
+{::comment:}
+... paragraph continues here.
+
+{::nokramdown:}
+This is not parsed *by* kramdown
+{::nokramdown:}
+{::kdexample:}
+
+As one can see from the above example, the syntax for extension blocks is virtually the same as for
+block IALs and ALDs, except that the colon of a block IAL has to be replaced by two colons, the name
+of the extension and then one or two colons. If one colon is used, it means that the extension has
+body text and continues until a matching ending line (as in the example above). If two colons are
+used, then the extension does not have a body, for example:
+
+{::kdexample:}
+# Header without id
+{::kdoptions:: auto_ids="true"}
+
+# Header with id
+{::kdoptions:: auto_ids="false"}
+
+# Header without id
+{::kdexample:}
+
+
+
+
+# Span Level Elements - Text Modifiers
+
+## Emphasis
+
+{::kdlink:: #emphasis part="emphasis"}
+
+Emphasis can be added to text by surrounding the text with either asterisks or underscores:
+
+{::kdexample:}
+This is *emphasized*,
+_this_ too!
+{::kdexample:}
+
+Strong emphasis can be done by doubling the delimiters:
+
+{::kdexample:}
+This is **strong**,
+__this__ too!
+{::kdexample:}
+
+The form with the asterisks can also be used to markup parts of words:
+
+{::kdexample:}
+This w**ork**s as expected!
+{::kdexample:}
+
+
+## Links and Images
+
+{::kdlink:: #links-and-images part="links and images"}
+
+A simple link can be created by surrounding the text with square brackets and the link URL with
+parentheses:
+
+{::kdexample:}
+A [link](http://kramdown.rubyforge.org)
+to the kramdown homepage.
+{::kdexample:}
+
+You can also add title information to the link:
+
+{::kdexample:}
+A [link](http://kramdown.rubyforge.org "hp")
+to the homepage.
+{::kdexample:}
+
+There is another way to create links which does not interrupt the text flow. The URL and title are
+defined using a reference name and this reference name is then used in square brackets instead of
+the link URL:
+
+{::kdexample:}
+A [link][kramdown hp]
+to the homepage.
+
+[kramdown hp]: http://kramdown.rubyforge.org "hp"
+{::kdexample:}
+
+If the link text itself is the reference name, the second set of square brackets can be omitted:
+
+{::kdexample:}
+A link to the [kramdown hp].
+
+[kramdown hp]: http://kramdown.rubyforge.org "hp"
+{::kdexample:}
+
+Images can be created in a similar way: just use an exclamation mark before the square brackets. The
+link text will become the alternative text of the image and the link URL specifies the image source:
+
+{::kdexample:}
+An image: ![gras](img/image.jpg)
+{::kdexample:}
+
+
+## Inline Code
+
+{::kdlink:: #code-spans part="code spans"}
+
+Text phrases can be easily marked up as code by surrounding them with backticks:
+
+{::kdexample:}
+Use `Kramdown::Document.new(text).to_html`
+to convert the `text` in kramdown
+syntax to HTML.
+{::kdexample:}
+
+If you want to use literal backticks in your code, just use two or more backticks as delimiters. The
+space right after the beginning delimiter and the one right before the closing delimiter are ignore:
+
+{::kdexample:}
+Use backticks to markup code,
+e.g. `` `code` ``.
+{::kdexample:}
+
+
+## Footnotes
+
+{::kdlink:: #footnotes part="footnotes"}
+
+Footnotes can easily be used in kramdown. Just set a footnote marker (consists of square brackets
+with a caret and the footname inside) in the text and somewhere else the footnote definition (which
+basically looks like a reference link definition):
+
+{::kdexample:}
+This is a text with a
+footnote[^1].
+
+[^1]: And here is the definition.
+{::kdexample:}
+
+The footnote definition can contain any block level element, all lines following a footnote
+definition indented with four spaces or one tab belong to the definition:
+
+{::kdexample:}
+This is a text with a
+footnote[^2].
+
+[^2]:
+    And here is the definition.
+
+    > With a quote!
+{::kdexample:}
+
+As can be seen above the footnote name is only used for the anchors and the numbering is done
+automatically in document order.
+
+
+## HTML Elements
+
+{::kdlink:: #html-spans part="HTML spans"}
+
+HTML is not only supported on the block level but also on the span level:
+
+{::kdexample:}
+This is <span style="color: red">written in
+red</span>.
+{::kdexample:}
+
+
+## Inline Attributes
+
+{::kdlink:: #span-inline-attribute-lists part="span IALs"}
+
+As with a block level element you can assign any attribute to a span level elements using a *span
+inline attribute list* (or short: span IAL). A span IAL has the same syntax as a block IAL and must
+immediately follow the span level element:
+
+{::kdexample:}
+This is *red*{: style="color: red"}.
+{::kdexample:}